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Host versions 

The documentation set which accompanies the occam 2 toolset is designed to 
cover all host versions of the toolset: 

• IMS D7305 - IBM PC compatible running MS-DOS 

• IMS D4305 - Sun 4 systems running SunOS. 

• IMS D6305 - VAX systems running VMS. 
About this manual 

This manual is the User Guide to the occam 2 toolset and is divided into two parts: 
'Basics' and 'Advanced Techniques' plus appendices. In addition some chapters 
are generic to other INMOS toolsets. 

Differences from the previous release of the Occam 2 toolset are listed immedi- 
ately after this preface. 

The basic section introduces the transputer and the toolset; provides an overview 
of the development cycle and then provides a chapter on each of the following: 

• Getting started - a tutorial. 

• Parallel programming using a single transputer 

• The configuration process. 

• Loading programs onto a transputer network. 

• Access to host services. 

• Debugging programs with the toolset debugger idebug. 

The advanced section is aimed at the more experienced user and covers the 
following topics: 

■ Advanced use ofthe configurer including placing code and data at specific 
memory locations and the software virtual through -routing mechanism. 

• Mixed language programming. 

• Developing programs for EPROM. 

• Low level programming facilities provided by the toolset e.g. dynamic code 
loading. 

The appendices provided in the User Guide include a glossary of terms and a bibli- 
ography. 
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Examples used in this manua[ 

Sources for many of the examples used in this manual can be found in the exam- 
ples/manuals subdirectory supplied with the toolset. This directory is further 
subdivided to group related example files, 'Readme' files provide guidance on the 
content of the examples subdIrectorieSj togetherwith brief instructions about how 
to build the examples. 

Only complete examples are provided in source form, code fragments listed in the 
manuals are not included. 

About the toolset documentation set 

The documentation set comprises the following volumes: 

• 12 IDS 366 01 Occam 2 Toolset User Guide (this manual) 

• 72 IDS 367 Oloccam 2 Toolset Reference Manual 

Provides reference material for each tool In the toolset including command 
line options, syntax and en'or messages. Many of the tools in the toolset 
are generic to other INMOS toolset produds, e.g. the ANSI C and 
FORTRAN toolsets, and the documentation reflects this - examples may 
be given in more than one language. The appendices provide details of 
toolset conventions, transputer types, the assembler, server protocol, 
ITERM files and bootstrap loaders. 

• 72 TDS 368 01 OCcam 2 Toolset Language and Libraries Reference 
Manual 

Provides a language reference for the toolset and implementation data. A 
list of the library functions provided is followed by detailed infomiation 
about each function. Details of extensions to the language are given in an 
appendix. 

• 72 TDS 379 00 Performance Improvement with the INMOS Dx305 occam 
2 Toolset 

This document provides advice about how to maximize the perfonnance 
of the toolset. It brings together information provided in other toolset docu- 
ments, particularly from the Language and Libraries Reference Manual. 
Note; details of how to manipulate the software virtual through-routing 
mechanism are also given in the User Guide. 

• 72 TDS 377 00 Occam 2 Toolset Handbook 

A separately bound reference manual which lists the command line 
options for each tool and the library functions. It is provided for quick refer- 
ence and summarizes information provided in more detail in the Tools 
Reference Manual and the Language and Libraries Reference Manual. 
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• 12 IDS 378 00 Occam 2 Toolset Master Index 

A separately bound master index which covers the User Guide, Toolset 
Reference Mariual, Language ar)d Libraries Reference Manual and the 
Performance Improvement document. 

Other documents 

Other documents provided with the toolset product include: 

• Delivery manual giving instailation data, this document is host specific. 

• Release notes, common to all host versions of the toolset 

• 'Occam 2 Reference Manual' published by Prentice Hall 

• 'A Tutoriat Introduction to Occam Programming' published by BSP Profes- 
sional Books. 

FORTRAN toolset 

At the time of writing the FORTRAN toolset product refen-ed to in this document 
set is still under development and specific details relating to it are subject to 
change. 

INQUEST 

The INQUEST products refen^ed to within this document are INMOS window- 
based debugging and profiling products, which may be bought separately and 
used with the toolset. 

Documentation conventions 

The following typographical conventions are used in this manual: 

Bold type Used to emphasize new or special terminology 

Teletype Used to distinguish command line examples, code fragments, 
and program listings from normal text. 

Italic type In command syntax definitions, used to stand for an argument 

of a particular type. Used within text for emphasis and for book 

yues. 

Braces { } Used to denote optional items in command syntax. . 

Brackets [ ] Used in command syntax to denote optional items on the 
command line. 

Ellipsis . . , Ingeneralterms, used to denote the continuation of a series. For 
example, in syntax definitions denotes a list of one or more 
Items. 

I In command syntax, separates two mutually exclusive alterna- 

tives. 
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transputers 



This chapter introduces transputers and the programming models which may be 
adopted when designing programs for the transputer. It describes the main 
features of the transputer and transputer systems, and introduces the Communi- 
cating Sequential Process (CSP) model of parallel processing, 

1*1 Transputers 

Transputers are high performance microprocessors that support parallel proces- 
sing through on-chip hardware and external communication links. They can be 
connected one-to-another by their INMOS serial links in application-specific ways 
and may be used as building blocks for complex parallel processing networks or 
as powerful dedicated microprocessors. 

The transputer is a compiete microcomputer on a single chip. In addition to hard- 
ware support for concurrent programming and inter-processor communication it 
contains: 

• A very fast (single cycle) on-chip memory. 

• A programmable memory interface that allows external memory and 
memory mapped devices to be added with the minimum of supporting 
logic. 

• System services for integrating transputer systems. 

• Real time clocks. 

• On the T8 series, an integral floating point unit. 

Figure 1.1 shows the generalized architecture of the INMOS family of 32-bit trans- 
puters. 16-bit transputers are also available, 

1.1.1 Transputer links 

Links allow processes running on connected processors to exchange data and 
synchronizetheiractivity.Supportforlinkcommunications is implemented in hard- 
ware on each transputer chip. Communications down links operate concun-ently 
with the processing unit and data can be transferred simultaneously on all links. 
Most transputers have four links except the IMS M21 2 and T400 transputers which 
have just two links. 
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Transputer links allow tools such as debugging programs to examine memory 
directly, from a remote processor. Links also provide a means of loading programs 
onto a network from the host down a single transputer link. Alternatively a network 
can be loaded via its links from a ROM on a single transputer 
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Figure 1.1 Transputer architecture 



1,1.2 Process scheduling 

Each transputer has a highly efficient run-time scheduler for time-sharing user 
application processes running on the same transputer. Within a single transputer 
communication between processes is supported using single words in memory. 
Processes waiting for input or output, or waiting for a time-slice, consume no CPU 
resources, and process context switching time is often less than one microsecond. 
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1.1.3 Real time programnning 

Features of the transputer prowde direct hardware support for real time program- 
ming. The key features are: 

• Direct and effjdent implementation of parallel processes in hardware. 

• Prioritization of parallel processes, 

• Simple implementation of interrupt handling software. 

• Easy programming of software timers, allowing close control of timing and 
non-busy polling. 

• Placement of variables at specific addresses in memory, for accessing 
memory mapped devices. 

Direct support for these features can be found in the current range of INMOS 
language toolsets, which use a common code format to facilitate code compati- 
bility. 

1 .1 A Multitransputer systems 

Multltransputer systems can be built very simply using the four high speed links; 
only two wires are required to connect two links together. The circuitry to drive the 
each link Is on the transputer chip. 

Transputers may be connected by their INMOS links in many configurations, 
depending on the needs of the appEication. Some possible an'angements of 
networi<s of transputers are illustrated in Figure 1.2. 
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Figure 1 .2 Transputer networks 
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1.2 Programming models 

Programs developed for running on a single transputer can be designed using 
traditional sequential programming methods or they can be designed to exploit 
parallelism. 

Parallelism can be designed into a program at two levels by dividing the program 
up into a number of independent communicating processes capable of operating 
in parallel. Such processes can either be mn on a single transputer or on a network 
of transputers. Programs designed for running on a network of transputers must 
use the parallel processing model. See section 1.2.1. 

Sequential programs can be run on a single transputer connected to a host Such 
programs can exploit the transputer architecture and software support provided 
by INMOS toolsets and /q systems products, see section 1.3. 



1.2.1 Parallel processing model 

The abstract programming model which the transputer supports is the Communi- 
cating Sequential Process (CSP) modei, based on the idea of independent parallel 
processes communicating through channels. Channels are one-way, point-to- 
point communication paths that allow processes to exchange data and synchro- 
nize their activity. (Further details can be found in 'Communicating Sequential 
Processes' - C.A.R, Hoare, published by Prentice Hall International). 

Each process is built from any number of parallel processes, so that an entire soft- 
ware system can be described in the form of a hierarchy of intercommunicating 
parallel processes. This model is consistent with many modem software design 

methods. 

Communication between processes is synchronized. When data is passed 
between two processes the output process does not proceed until the input 
process is ready and vice versa. 

Communication between software processes running on the same transputer 
takes place through internal channels implemented as words in memory; commu- 
nication between processes running on connected processors is driven by the link 
interfaces and takes place through the transputer links. 



1.3 Transputer products 

There is a complete family of transputer devices, including: 32-bit and 16-bit 
processors; a link switch; and an adaptor from a parallel port to a [ink. 
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A wide range of INMOS z'q systems transputer boards is avaJEable for specific 
liosts. These can be used for: 

• Developing and debugging transputer software 

• Improving system perfomiance (as accelerator boards) 

• Loading software onto embedded systems 

• Building specific transputer networks 

• Specific applications such as SCSI interfacing. 



1.3.1 Toolset products 

The INMOS compiler toolsets are complete cross-devefopment systems fortrans- 
puters. They allow transputers to be programmed sequentially and in parallel 
using high-level languages, making optimum use of the transputer's butit-ln 
parallel features. The combination of access to parallelism from a high level 
language and a set of tools for configuring and loading programs on transputer- 
based systems fonns a powerful development system for all parallel and 
embedded sofh/vare applications. 
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This chapter introduces the Occam 2 toolset. It describes the main features of the 
toofset and provides introductions to the occam 2 compiler, the toolset linker, the 
configuration system, and mixed language programming. A summary of the 
toolset components is given at the end of the chapter. 

2.1 Introduction 

The Occam 2 toolset is a software cross-development system for transputers, 
hosted on PC/MS-DOS, Sun 4/SunOS and VAXA/MS systems. It consists of an 
Occam 2 compiler, a multilanguage linker, configuration and code collection tools, 
a host file server, and program development tools. 

The program development tools include an interactive and post-mortem 
debugger, a librarian, an object code lister, a makefile generator, and EPROM 
programming tools. Together with the compilation system, these form an inte- 
grated support and deveiopment environment for the programming of transputers 
and transputer-based hardware. 

2.2 Toolset features 

This toolset incorporates a number of important features; 

• Standard object code format generated by the compiler and linker 

• An updated occam 2 compiler with language improvements, facilitating 
full exploration of a programming model designed to support parallelism. 

• A configuration language which is an extension to Occam and facilitates 
the mapping of software to hardware. The language supports: 

o Automatic placement of channels using software routing and multi- 
plexing processes. The ability to place channels is also retained as 
an option. 

o Placement of code and data at specific memory addresses. 

• Support for mixed language programming through the configuration 
system and by specific support in the compiler 

2.3 Standard object file format 

The current range of INMOS toolsets generate object code in an intermediate fomi 
known as TCOFF (Transputer Common Object RIe Fomiat), that can be 
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processed by other tools in the toolset. This standard has been adopted for the 
development of transputer toolsets and enables modules written in different 
languages to be freely mixed in the same system. 



2.4 Occam 2 compiler 

The Occam 2 compiler complies Occam source code contained within standard 
host format text files. Any text editor that produces ASCI I files can be used to create 
the Occam source, occam source code must conform to the definition of occam 
2 which is described In the OCCam 2 Reference Manual. The compiler implements 
a number of non-standard language extensions (see appendix A in the Occam 2 
Toolset Language and Libraries Reference Manuat}. 

The compiler targets the cun-ent range of IN MOS tra nspulers . Code may be gener- 
ated for specific processor types or for related groups (see appendix B in the 
occam 2 Toolset Reference Manual). 

Code may be generated in HALT, STOP, or UNIVERSAL occam error modes. The 
error mode must be the same (or compatible) for all units In the compilation, and 
must be the same as the linker error mode. 



2.4.1 Programming model 

The occam programming model consists of parallel processes communicating 
over channels. Processes may be on the same or different processors, communi- 
cating over internal channels or transputer links. 

Occam 2 has been optimized for the architecture of the transputer- parallelism 
IS expressed directly in the language. The use of a fonnal mathematical framework 
enables OCCam code to be extensively checked at compile time and supports 
formal program proving and optimization. The inherent security of Occam code 
coupled with efficient use of the transputer's parallel features make it a powerful 
tool for the development of concurrent systems. 

2.4.2 Language extensions 

The compiler implements a number of language extensions. These are compiler- 
dependent and do not form part of the OCCam 2 definition. 

Directives supported are #INCLUDE, #USE, #comment, #import, #Option, and 
ttPRAGMA. #PRAGMA supports a number of compiler-dependent functions, 
including foreign language code import and name translation. These are fully 
described in section 1.12 of the Occam 2 Toolset Reference ManuaL 

Other language extensions supported by the compiler are: assembly code inser- 
tion; memory placement; and extended channel and array constructs. See 
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appendix A of the OCCQm 2 Toolset Language and Libraiies Reference Manual 
for details. 



2A3 Occam libraries 

A comprehensive set of libraries and include files are supplied with the toolset. 
They include the compiler libraries which form part of the standard support for the 
Occam language and a set of user libraries for use by the applications 
programmer. 

The compiler libraries are used internally by the compiler; they are not intended 
for general use by the programmer, although some routines have been made 
visible (see section 1 .3 in the occam 2 Toolset Language and Libraries Reference 
Manual). The compiler automatically loads the correct set of nautines for the 
selected en-or mode. Compiler libraries are specrfied to the linker by means of 
target-specific linker indirect files (see section 3.11.2). 

The user libraries provide application-level support. There are libraries to support: 
single length, double length, and T4-optimized maths; file-based, stream-based, 
and DOS-specific l/o; string handling; type conversion; link error handling; CRC 
coding; and debugging. Constants and definitions are supplied in include files. See 
the Occam 2 Toolset Language and Libraries Reference Manual for details. 

2.4,4 Low level progrannming 

Sequences of transputer instructions can be embedded in Occam code using the 
ASM construct. This can be useful for optimizing critical sections of code^ but the 
lacility should not be over used because it reduces the compiler's opportunity to 
check code. 

A set of procedures are provided v^ich enable a separately compiled and linked 
Occam procedure to be called at mntime and incorporated in a running occam 
program. This facility is aimed at experienced toolset users. 

Full descriptions of these facilities are given in chapter 13. 

2.5 Multilanguage linker 

The toolset linker takes compiled code and libraries and generates a linked unit 
in TCOFF format. Code can be input from any compiler system which generates 
TCCFF code, for example, the INMOS ANSI C compiler ice. Linker indirect files 
(command scripts to the linker) may be used to spectfy operations to the linker; for 
example, as in the linker indirect files provided with the toolset for referencing the 
compiler libraries (see section 3.11.2). 

Linker directives, which must be referenced using linker indirect files» may be used 
to modify the content of the linked unit. Linker directives are described in section 
9.4 of the occam 2 Toolset Reference ManuaL 
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2.6 Configuration system 

The configurer occonf generates configuration information for transputer 
networlcs from a textual configuration description containing separate descriptions 
of hardware and software. Mapping of software to hardware is performed 
according to a mapping description written by the user, while the mapping of chan- 
nels to links can be performed automatically by the configurer or be specified by 
the usen 

The too] prepares the program for configuring on a specific arrangement of trans- 
puters by analyzing the nehvorit description file in conjunction with the configura- 
tion file, and creating a configuration data file for the code collector tool to read. 
The code collector then generates the program image which may be loaded onto 
the hardware. 

The configuration language used to write the configuration description is an exten- 
sion of Occam. It allows software and hardware networks to be described sepa- 
rately and joined by an optional software-to-hardware description. The language 
Is a simple declarative language incorporating high-level constructs such as repli- 
cation and conditional statements. 



2.6.1 Software routing and multiplexing 

The configurer uses software routing and multiplexing software to implement 
channel communication over viriuaUinks. This allows many virtua! channels to use 
a single physical link between processors and enables processes on non-adjacent 
processors to communicate directly 

Software routing and multiplexing Is perfonned automatically by the configurer and 
requires no intervention on the part of the programmer. Existing configuration code 
can be reused - virtual routing wilJ be employed where required unless virtual 
routing is specifically disabled by the configurer NV option. This option effectively 
a[lows users to revert to the functionality of the D7205/D4205/D5205/D6205 tool- 
sets. 

Future INMOS transputer devices v\flll implement virtual channel communication 
directly in hardware. The presence of a software virtual routing configurer in the 
current toolset provides some of the functionality of future processors and is 
intended to ease the transition to the next generation of transputer products. 

2.6.2 Code and data placement 

Normally, the configurer will use up the available memory accessible to a 
processorby allocating the various parts of the application from the lowest address 
upwards. However, it is sometimes necessary to specify exactly where a piece of 
code or data should reside. The configurerallows the user to state where the code, 
workspace (stack) or vectorspace of an Occam program must be placed In 
memory. 
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The transputer has some very fast RAM which the application may be required to 
use in a special way. The configurer can also be told to avoid this area of memory 
so that the user has free access to JL 



2.7 Mixed language programming 

The use of standard TCOFF format allows compiled and finked modules from 
different language sources e.g. C and occam, to be mixed in the same system- 
Individual linked units in TCOFF format can be mixed in any combination and 
placed on any processor in the network. 

Calling modules written in other languages Is also possible. For example, occam 
can call C by using library routines to set up and terminate the static and heap 
areas. C can call occam using a 'nolink' pragma which directs the G code to be 
compiled vrithout a static base parameter, or a dummy static base parameter can 
be declared In the occam code. 

In all mixed language calls, parameters and retum values passed must be of the 
con'ect type. Lists of type equivalents between C, and OCCam are given in chapter 
11. Where character sets differ between languages, 'translate' pragmas available 
in the compilers can be used to create acceptable aliases. 
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2.8 Toolset summary 

The components of the toolset are listed in Table 2.1. Descriptions of the tools can 
be found in Chapter 3 which also describes the main stages of program develop- 
ment. 



Tool 


Description 


icollect 


The toolset code collector. Collects linked units into a single file 
for loading on a transputer network. Takes as input a configura- 
tion data file or a single linked unit. 


idebug 


The toolset network debugger. Supports post-mortem and inter- 
active debugging of transputer programs. 


idump 


The memory dumper. An auxiliary tool for use when debugging 
programs on the root transputer 


iemit 


The transputer memory configuration tool. Used for evaluating 
and defining memory configuratons for later incorporation into 
ROM programs. 


ieprom 


The EPROM program formatter tool. Formats transputer boot- 
able code for input to ROM programmers. 


ilibr 


The toolset librarian. Builds libraries of compiled code. 


ilink 


The toolset linker. Resolves external references and links sepa- 
rately compiled units into a single file. 


ilist 


The binary lister Disassembles and decodes object code and 
displays Infomnatlon in a readable fonn. 


imakef 


The Makefile generator Generates Makefiles for input to MAKE 
programs. 


iinap 


The map tool which gives the addresses of functions and vari- 
ables used by the program. 


i server 


The host file server. Loads programs onto transputer hardware 
and provides runtime access to host services. 


isim 


The T425 simulator. Simulates program execution on an IMS 
T425 transputer and provides simple debugging facilities. 


iskip 


The skip loader tool. Used with iserver to load programs onto 
external nehworks over the root transputer. 


oc 


The Occam compiler, Complies code for the cun^ent range of 
INMOS transputers. 


occonf 


The Occam configurer. Reads a configuration description and 
produces a configuration data file for the code collector. 



Table 2,1 The Occam 2 toolset 
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This chapter gives an overview of the program development cycle using INMOS 
toolsets. It briefly describes the purpose of each tool and outlines how to use them 
in developing, configuring, loading and running transputer programs from the host 
system. The chapter also provides details of command line defaults, environment 
variables, and host dependencies. 

3.1 Introduction 

This toolset is one of a range of cross-development systems designed and devel- 
oped by INMOS for transputer applications. Toolsets which are available include 
ANSI C, Occam, and FORTRAN products. 

The toolsets have been designed to make program development as simple as 
possible. Each toolset features a particular language compiler with full library 
support and then uses a common set of tools for further development stages. For 
example, tools are included for: creating libraries, linking code, configuring soft- 
ware to run on transputer nehwori<s, producing the program bootable file and for 
loading the application onto hardware. This means that one development method- 
ology can be used to develop programs using a number of different programming 
languages. Indeed one of the features of the toolsets is that they facilitate mixed 
language programming. 

The toolset includes support for the following functions: 

• building executable code; 

• loading and running code; 

• debugging programs; 

• preparing programs for ROM; 

• obtaining information about object files. 

3.2 Program development using the toolsets 

Programs may be developed on the user's host system before down-loading onto 
either a single transputer or a network of transputers to mn. 
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Executable code is loaded onto a transputer either from ROM or from the host 
system via a single transputer link onto the 'rooV transputer i.e. the transputer 
connected to the host. Loadable code is propagated to any other transputers in the 
network via the interconnecting transputer links. 

Creation of executable code for a transputer or transputer network takes several 
stages involving the use of specific tools at each stage: 

1 Software design. 

The software designer can specify the components of a system In terms 
of comnnunicating processes. The overall design can be directly expressed 
in the parallel constnjcts of the language. 

Alternatively conventional sequential programs can be developed for 
mnning on a single transputer. 

2 Write the source. 

Source code can be written using any ASCII editor available on the host 
system. Code can be divided between any number of source files. Source 
code must conform to the syntax required by the particular language 
compiler used. For C this is the ANSI standard; Occam source code must 
confonn to the Occam 2 language definition and FORTRAN source code 
to FORTRAN-77 syntax. 

3 Compile the source. 

Each source file is compiled using the appropriate language compiler to 
produce one or more compiled object files in TCOFF format. Each file must 
be compiled forthe same transputer type orfora transputer class covering 
several compatible types. (More information about transputer types and 
classes is given in the appendices of the accompanying Toolset Reference 
^fa/^ua/). Commonly used object code can be combined into libraries using 
the librarian ilibr. 

4 Link the compiled units. 

The compiled object files and libraries are linked together using ilink. 
This generates a single file called a linked unit in which all extemal refer- 
ences are resofved. The linking operation links in the library modules 
required by the program, which are selected by transputer type from the 
compiled library code. Object files for input to the linker can be generated 
by any TCOFF compatible compiler. 

Programs developed for the transputer may comprise one or more linked 
units, created from separately compiled code and library modules. Linked 
units are assigned to run on a single transputer or a networit of transputers 
during configuration. A linked unit is the smallest unit of code which may 
be placed on a transputer 
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5 Configure the program. 

Configuration is the process of defining how the application is to be run on 
hardware. It is achieved by writing a configuration description, assigning 
linked units to specific processors and optionally connecting them by chan- 
nels. By changing the configuration description it is possible to run a 
program on either a single transputer or on different network topologies. 
The description is processed by the configurer tool to produce a configura- 
tion data file. Configuration is used for both single and multiprocessor 
transputer programs. 

The language used to write the configuration description is detennined by 
the toolset. The C and FORTRAN toolsets provide a common configurer, 
icconf which can be used to configure programs written in C, 
FORTRAN-77 or occam. Using icconf, modules written in different 
languages can be mixed at configuration level, see Chapter 11. The 
Occam toolset configurer occonf is designed to exploit the parallel 
programming model of the language and is specific to the occam toolset. 

6 Generate an executable fIJe. 

Before a program can be run it must be made 'bootable'. This involves 
adding bootstrap information to make the program loadable and is 
achieved using the collector tool. 

The configuration binary file generated by the configurer is read by the 
code collector icolleet which generates a single executable file for a 
transputer network. The collector can generate either a file which is suit- 
able for booting onto a transputer networit via a transputer link or one for 
booting from ROM. The default behavior of the tool is to produce a boot- 
from-Hnk executable. 

Whether a boot-from-ROM executable Is generated is determined by 
command line options specified to the configurer prior to creating the 
configuration binary file. 

7 Load and run the program. 

An executable boot-from-link file is loaded and run on the transputer 
network down a host link using iserver. Once loaded the code begins to 
execute immediately. The server tool maintains the environment that 
supports the program's communication with the host. 

8 Place in ROM. 

Executable boot-from-ROM filesfor embedded systems, are processed by 
the iepromtool to produce an output file which is suitable for blowing into 
ROM, Such files may be configured to run from ROM or from RAM. 

Programs to be placed in ROM are often developed first as boot-from-link, 
until they are en-orfree. They are then prepared for ROM by re-submittIng 
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them to the configurer and collector, specitylng different command line 
options, prior to using the epnDm tools to format them for ROM. 

Program development is supported by additional tools which provide fecilities for 
debugging, creating object code libraries, automating the program build, and 
obtaining infonnation about object files. 

Figure 3,1 summarizes the main development stages. 
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Figure 3.1 Main development stages 



3.2.1 Compatibility with previous toolset releases 

For single transputer programs the configuration stage of the development 
process can be omitted. Instead bootable code can be generated directly from the 
linked unit by specifying a collector command line switch. 

This mode of development is not recommended, however, and may not be 
supported in future toolset releases. 
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3.3 Compiling 

INMOS compilers produce compiled code for specific processor types or for a 
group of related processors called a transputer class. Each compiler has the same 
set of options to select the target transputer these are listed in the appendices to 
the accompanying Toolset Reference Manual. The role of transputer types and 
classes in compilation and program development Is also described in these appen- 
dices. 

The cun-ent range of INMOS compilers generate object code In an intermediate 
fonri known as TCOFF (Transputer Common Object File Rjrniat). This standard 
has been adopted for the development of transputer compilers and enables 
modules written in different languages to be freely mixed in the same system. 

Supplied with each compiler is a set of language specific libraries which provide 
runtime support, input/output operations, mathematical functions etc. Support is 
also provided for language extensions, concurrent programming and software 
configuration of a network. 

The compiler and libraries supplied with this toolset are introduced in Chapter 2. 
Detailed information about the compiler and libraries can be found respectively in 
the Toolset Reference Manual and the Language and Libraries Reference Manual 
supplied with this toolset. 

3.4 Tools for building executable code 

Three tools are used in sequence to generate the loadable file from compiled 
object code: 

• ilink - the toolset linker which links separately compiled units 

• icGonf or occonf - the configurer tool which generates a configuration 
binary file. 

• icollect - the code collector which generates a bootable file for a trans- 
puter networic fn^m the configuration data file. 

The configurer works on a configuration source file written by the programmer. The 
output of the configurer is an information file which is processed by the collector 
to generate an executable or bootable file. The executable file contains all the 
information needed to distribute, load, and run the program on a specific network 
of transputers. 

3.4.1 Linker -ilinX 

The toolset linker ilink links separately compiled modules and libraries into a 
single code unit, resolving extemal references and generating a single linked unit. 
Linked units are referenced directly from configuration descriptions to map soft- 
ware onto specific arrangements of transputers. 
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Library modules are linked in with the program by a linker indirect file which must 
be specified on the linker command line. (In the C toolset this Is known as a startup 
file). The con*ect linker indirect file must be specified, depending which version of 
the compiler or mntime libraries is required, see section 3.11 for further details. 

3A2 Configurer 

The configurer generates configuration informatfon for transputer nehworks from 
a textual configuration descnption. The tool prepares the application for confi- 
guring on a specific arangement of transputers by analyzing the configuration 
descnption and creating a configuration binary file for the code collector tool to 
read. 

Configuration descriptions are written using the transputer configuration language 
appropriate to the configurer used, see above. 

3.4.3 Code collector - icollect 

The code collector tool icollect takes the binary file generated by the configurer 
(which references the linked code) and generates a single file that can be loaded 
and run on a transputer network. The collector generates bootstrap and loading 
code. The output from the collector contains bootable code modules together with 
distribution information that is used by the loading code to place the correct 
modules on each processor. 

The collector may also generate non-bootable output files which may be dynami- 
cally loaded or loaded onto ROM or RAM. 

3.5 Loading and running programs 

Boot-fro m-link code for single transputers and transputer networks is output from 
icollect and is loaded onto the transputer hardware using the host file server 
toof i server. The iskip tool can be used in combination with iserver to load 
a program onto an external network, skipping the root transputer (the transputer 
connected to the host). 

Boot-from-ROM code is processed by the eprom programming tools introduced 
in section 3.7, 

3.5.1 Host file server - iserver 

The host file server iserver is a combined host server and program loader tooL 
When invoked to load a program it both loads the code onto the transputer hard- 
ware and provides runtime services on the host for the transputer program such 
as i/o. 

3.5.2 Skip loader - iskip 

The skip loader iskip forces a program to be loaded over the root transputer (the 
transputer connected to the host), iskip is loaded prior to invoking iserver for 
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loading user programs onto a transputer board and prevents the root transputer 
being used as part of the configured network. It continues to run as long as the user 
program and passes messages between the host and the network. 

The tool is useful when debugging programs because it leaves the root transputer 
free to run the debugger. This avoids the use of idunqp to save the pnDgram image 
and 3.\\ows the user program to mn on a network that would not support the 
debugger e.g. because it has not enough memory. 



3.6 Program development and support 

Several tools are provided to assist in program development: 

• idebug - the interactive network debugger. 

• idump - the memory dump tool for use with idebug when debugging 
programs on the root transputer. 

• ilibr - the librarian which generates libraries of compiled code. 

• Hist - the binary lister which decodes and displays object files. 

• imakef - the Makefile generator which creates Makefiles for use with 
MAKE programs. 

• imap - the map tool which generates a memory map of the functions and 
variables used by the program. 

• isim-theT425 simulator tool which enables programs to be executed in 
the absence of transputer hardware. 

3.6.1 Network debugger - idebug 

The network debugger id«bug provides post-mortem and interactive debugging 
for transputer programs. It allows stopped programs to be analyzed from their 
memory image or from image dump files {post-mortem debugging) and supports 
interactive execution of a program using breakpoints {breakpoint debugging). 
Breakpoints can be set on source lines or memory addresses, variables can be 
inspected and modified, and the program restarted with new values. 

idebug provides two debugging environments: a symbolic environment which 
allows a program to be debugged from source code; and the Monitor page enwon- 
ment which allows a program to be debugged at machine level. 

The debugger inserts no additional code into the program, but uses parallel 
processing to monitor the program and display its state. This guarantees that the 
code generated when debugging is disabled will always mn in the same way as 
the final version of the pnDgram. 
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3.6.2 Memory dumper - idunp 

The special debugging tool idump is provided to assist with the post-mortem 
debugging of programs that run on the root transputer Since idebug executes 
on the root transputer and ovenvrites the program image, idump must be used to 
save the image to a file which is later read by the debugger. 

3.6.3 Librarian - ilibr 

The librarian ilibr creates libraries of compiled code for use in application 
programs. 

A library is a concatenation of compiled files called modules. The linker only links 
in modules that are required. 

Code compiled by compatible TCOFF toolsets can be mixed in the same library. 

3.6.4 Binary lister - ilist 

The binary lister ilist decodes object code files and displays data and informa- 
tion from them in a readable form. Command line options select the category and 
format of data to be displayed. 

Examples of the kind of information that can be displayed are symbolic names, 
code listing, the modular structure and Indexing of libraries and external reference 
data. 



3.6.5 Makefile generator- imakef 

The Makefile generator imaJcef creates Makefiles for specific program compila- 
tions. Coupled with a suitable 'make' program it can automate building of execut- 
able code and greatly assist with code management and version control. Note: a 
make program is not supplied. 

imakef constructs a dependency graph for a given object file and generates a 
Makefile in standard format. In order to make use of the tool a special set of file 
extensions for source and object files must be used throughout program develop- 
ment, imakef uses these file extensions to deduce target transputer types and 
other options. These extensions are described for imakef in the Toolset Refer- 
ence Manual. 



3.6.6 Memory map tool - imap 

The memory map tool imap takes the text output fiTDm the toolset compiler, linker 
and collector and creates a map of the absolute addresses of the static variables 
for functions. The memory map is output on the dispiay screen or redirected to a 
file as the user wishes. 
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3.6.7 T425 simulator - isim 

The T425 simulator tool isim simulates the operation of the T425 transputer, 
enabling programs to be executed in the absence of transputer hardware. 

Run In interactive mode it provides low level debugging features such as the 
inspection of variables, registers and queues, disassembly of memory, break 
points, and single step execution. 

Batch mode operation of the simulator allows programs to be executed without 
entering the debugging environment. 



37 EPROM programming 

Two tools assist with the installation of programs into ROM, namely, the EPROM 
programmer ieprom and the memory configurer iomit. 



3.7.1 EPROM programmer- ieprom 

The EPROM programmer ieprom converts ROM-bootable files generated by 
icollect into a fonnat suitable for input to ROM programmers. Files can be 
generated for input to ROM loading programs provided for specific ROMs, or 
dumped in straight hexadecimal or binary for input to the users' own ROM loaders. 

ieinit output can also be interpreted and the appropriate bit pattem included In 
the ROM, see below. 



3.7.2 Memory configurer- iemit 

Some transputers have programmable memory interfaces which may be confi- 
gured for a particular memory design. 

The memory interface configurer iemit allows specific transputer memory 
configurations to be evaluated and can output a configuration file for incorporation 
into ROM by ieprom. The completed configuration file can be read by ieprom 
and interpreted for inclusion in the ROM at the con-ect address. The transputer can 
automatically read this data when it is reset and use it to configure its memory inter- 
face. 
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3.8 File types and extensions 

The cun-ent range of INMOS toolsets use, by default, a standard set of file exten- 
sions to identify specific files such as source, compiJed object, linked units and 
bootable files. Certain file extensions are assumed by the tools on input, and 
others generated by the tools on output, unless extensions are explicitly given on 
the command line. For example the compiler adds the extension ,tco to the 
output file unless otherwse specified. 

The adoption of a standard system allows file extensions to be omitted on the 
command line, and pemiits host file system utilities to be used. The system is 
designed to form an integrated whole and reflects the architecture of toolset 
compilation. 

The standard set of file extensions is not mandatory and may be modified 
according to personal choice, unless imalcef is to be used to build the makeflfe. 
imakef uses a special scheme to identify processor types and error modes, as 
described below. 

The standard system has the advantage of ready defaults but may not be readily 
mapped onto existing development schemes. However, if it is decided to adopt a 
personalized scheme then it should be reasonably formal and conlroHed, which 
is especially important acn^ss development teams. 

Some extensions recognized by the toolset are used for convention only and are 
not interpreted by the tools in any special way For example, the . lib suffix for 
fibrary files and the , inc suffix for include files are looiset programming conven- 
tions. 

The main file extensions used in developing transputer programs are listed in 
Table 3.1 . A full list of all file extensions used by the toolset with descnptions of the 
file types is given in the appendices to the accompanying Toolset Reference 
Manual. 

Figure 3.2 illustrates the pnagram development process in terms of the file exten- 
sion defaults used by the toolsets. The extensions assumed on input and gener- 
ated on output are used to represent source and target files. Figure 3.2 highlights 
the differences between the different language toolsets and shows how software 
can be developed to be loaded onto transputer hardware directly via a transputer 
link or held in ROM. 
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Extension 


Description 


.btl 


Bootable code file. Created by icollect. 


■ btr 


Executable code minus bootstrap infomiation. Used for input to 
the EPROM tool. Created by icollect. 


■ c 


C source files. Assumed by ice, the ANSI C compiler. 


,cfb 


Configuration data {binary) file. Created by the configurer 


.cfs 


Configuration description (source) file, read by the C configurer 
icconf. 


.clu 


Configuration linked unit. Created by occonf. 


.f77 


FORTRAN source programs. Assumed by if77, the 
FOR IKAN-77 compiler 


-b 


Header files for use in C source code. 


.inc 


include files named in #INCLUDE compiler directives for 
Occam, or #include statements in configuration descrip- 
tions or in FORTRAN-77 statements. 


.Ibb 


Library build file. Input to iiibr. 


.lib 


Library object file. Created by ilibr. 


.liu 


Library usage files. Created and used by imakef . 


.Iku 


Linked unit. Created by ilink. 


■ Ink 


Linker indirect file. Input to ilink. 


.occ 


Occam source files. Assumed by oc, the Occam 2 compiler. 


.pgm 


Configuration description (source) file, read by the Occam confi- 
gurer ocGonf . 


,rsc 


Dynamically loadable code file. Created by icollect. 


.tco 


Compiled code file. Created by all INMOS TCOFF compilers. 



Table 3.1 Toolset main file extensions 

3.8.1 File extensions required by imakef 

The Makefile generator imafcef requires a special set of file extensions to be used 
for compiled and linked object files. The extensions define the architecture of 
toolset compilation so that imakef can trace file dependencies and create the 
correct sequence of bui[d commands. They are also used to deduce the transputer 
type and en'or mode for each unit. 

For details of the file extensions that you must use with the imakef tool see the 
appendices of the accompanying Toolset Reference Manual. 
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.^nziT. 




Figure 3.2 Development cycle 
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3.9 Error reporting 

If a tool detects an error in its input, it is reported in a standard format. This cxintains 
the name of the tool, a severity level, and some explanatory text explaining why 
the en-or occun-ed. Errors found in files or the file system may also generate a file- 
name and line number. Standardization of the format is designed to improve en-or 
reporting and to support automated en^or handling by host system utilities. 

For example: 

Serious-ilibr-mymod. txt-bad format: not a TCOFF file 
where: mymod. txt is the name of the input file causing the problem. 

Note: Messages that are part of the normal operation of the tool, for example, diag- 
nostic messages generated by the compiler, and messages from the debugger 
and simulator tools, are not required to conform to the standard and may be 
displayed in special formats appropriate to the tool. The formats will become 
familiar with use of the tool. 

Details of the standard format can be found in the appendices of the accompanying 
Toolset Reference ManuaL 

3.10 Host dependencies 

The toolset uses a host to develop code which is then down loaded onto a trans- 
puter or transputer network. 

The toolset can be hosted on one of several different platforms, and the tools are 
designed to blend in as far as possible with the operating system. Source and 
object code is portable between all systems. 

The toolset is available for the following host systems: 

• IBM 386 PC {and compatibles) running MS-DOS 

• Sun 4 running SunOS 

• VAX running VMS. 

Differences between the operation of the tools on the various platforms are minor 
and reflect the 'flavor' of the particular operating system. 

Host system dependencies are as far as possible made invisible to the user. The 
few differences are some minor variations in command line syntax, host-specific 
library routines, directory names, and environment settings such as search paths 
and global variables. Each is described briefly below. 

Command line syntax 

The major difference between host implementations is the use of the host system 
option prefix. For UNIX based toolsets {Sun 4) the prefix character is the dash '-'; 
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for MS-DOS and VAXA/MS based tooteets the prefix character is tlie forward slash 

7'. 

For consistency between implementations, the case of options is not significant. 
However, the host syntax for filenames is used (see below), which means that on 
UNIX systems the case of filenames is significant. 

Other command line syntax conventions are identical in all implementations and 
are described in the appendices of the accompanying 7bo/se/ Reference Manual. 

3.10.1 Filenames 

Filenames, with or without a directory path, conform to the normal host system 
conventions excepf that characters which can be interpreted as directory separa- 
tors (on any of the supported hosts) must not be used in filenames. This prohibits 
the use of the following characters; colon ':', seml-colon ';', forward slash '/', 
backslash '\ ('¥' for Japanese systems), square brackets '[]', round brackets 
' { ) ', angle brackets 'o', exclamation mark ' ! ',or the equals sign '='. 

In addition the linker cannot handle filenames which begin with a hash '#' or with 
two dashes ' — ', These are used to identify commands and comments within linker 

indirect files. 

Where the host operating system allows logical names to be used in place of fife- 
names, such as with VMS, the toolset allows logical names to be used, but the 
name must be followed by a dot ' . '. This prevents the tool fi-om adding an exten- 
sion, which would generate a host file system error. 

3.10.2 Search path 

All tools which use or generate filenames use a standard mechanism for locating 
files on the host system. The same mechanism is used in all operating system 
versions of the toolset Briefly, the search mechanism is based on a list of directo- 
ries to be searched in sequence. 

If a directory path is specified only this directory is searched. If the file is not found 
on the path an en-or is generated. Relative pathnames are treated as relative to 
the current directory, i.e. the directory from which the tool is invoked. 

If no directory path is specified the cun^ent directory is searched followed by the 
directories specified in the i search environment variable. 

Details of how to set up a search path on your system can be found in the Delivery 
Manual that accompanies the release. 

Full details of the mechanism used in file searching can be found in the appendices 
of the accompanying Toolset Reference Manual. 

3.10.3 Environment variables 

The toolsets use a number of environment variables on the host system. Use of 
these variables is optional but if defined they will Influence the behavior of certain 
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of the tools on your system. Further infonnation is given in the accompanying 
Toobet Reference Manual. 



Variable 


Meaning 


ICONDB 


Defines the connection database to be used by iserver. 


ISESSION 


Defines the session manager configuration file to be used by 
iserver. Defaults to session, cfg if not defined. 


ISEARCH 


The search path; i.e. the list of directories that will be 
searched rf a pathname is not specified. Pathnames must be 
terminated by the standard directory separator character for 
the system. Used by aJJ tools that read and write files. 


ISIMBATCH 


Used by isim to enable/disable batch mode. Values can be 

VERIFY or NOVERIFY. 


ITEBM 


The file that defines terminal keyboard and screen control 
codes. Used by idebug, isim and ieiait. 


IB0ARDSI2E 


The size (in bytes) of memory on the transputer board. Used 
when loading non-configured programs. 


TRANSPUTER 


Defines the capability (user link name) to be used by the 
server Can be ovemdden by iserver command line option. 


IDEBUGSIZE 


The size (in bytes) of memory a>nnected to the root trans- 
puter Used by idebug. 


toolnameARG 


Default command line arguments. Applies to certain tools 
only See section 3.10.4. 



Table 3.2 Toolset environment variables 

The exact commands used to define environment variables depend on the oper- 
ating system. For example, under MS-DOS they are defined using the set 
command; on VAX systems running VMS they can be set up either as logical 
names or as VMS symbols. Examples of how to set up environment variables can 
be found in the Delivery Manual that accompanies the release. 

For IBOARDSIZE and idebugSIZE the value can be given in decimal or hexade- 
cimal formaL Hexadecimal numbers must be preceded by '#' or '$'. Leading and 
trailing spaces may not be given. 

Note: If IBOARDSIZE is speci^ed incon^ectly, for example as a character or string, 
the system defaults to a board size of (zero) and the program cannot be mn. If 
IBOARDSIZE is explicitly set to a very small value a similar error may occur 

3.10.4 Default command Une arguments 

An environment variable can be defined on the system to specify a default set of 
command line arguments for certain tools. The variable name must be defined in 
upper case and is constructed from the tool name by appending the letters 'ARG'. 
For example, the variable for ilink is ilinkarg. 

Tools for which a defeult command line can be defined, and the variables used to 
define them, are listed below. 
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Tool 


Variable 


ice 


ICCASfi 


if77 


IF77ARG 


ilink 


ILINKAR6 


icconf 


ICCONFARG 


icollect 


ICOLLECTARG 


ilibr 


ILIBRARG 


ilist 


ILISTARG 



Table 3.3 Environment variables for invoking tools 

Command line parameters must be specified within eacli variable using the 

specific syntax required by each tooL 



3.11 Linker startup and indirect files 

Linker indirect files are text files containing lists of input files and commands to the 
linker. 

A number of linker indirect files are supplied with each toolset. The purpose of 
these files is to reference various runtime libraries (or In the case of Occam, 
compiler libraries) required to link application programs. When specifying the 
program modules to be linked, the appropriate linker Indirect file must be Included 
on the linker command line, as described in the reference chapterfor ilink in the 
accompanying Toolset Reference Manual. 



3.11.1 ANSI C Toolset 

For C the linker indirect files are known as linker startup' files. Tliey reference 
runtime library fifes which provide the runtime environment for the program and 
define which version of the C runtime initializatron code is used by specifying a 
main entry point. This is the name of the routine wheh is called by the transputer 
bootstrap code or configuration system code, in order to start the C program 
executing. 

Most C programs will require one of the three linker startup files listed in table 3.4. 
Two files are provided for use with configured programs; one with the full runtime 
library and one with the reduced runtime library. Ttie reduced library does not 
support host I/O. It is recommended that all programs are configured. 

The third file is provided for use vnth non-configured programs using the full 

runtime library. 

Special linker startup files whk:h do not specify a main entry point are described 

In section 3.11.4 below. 
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Startup file to support: 


Configured programs 


Non-configured 
programs 


Full runtime library 


Reduced runtime 
library 


Full runtime library 


cstartup.ink 


ca tartrd. Ink 


cnonconf . Ink 



Table 3.4 C startup files 

cs tar tup , Ink 

This linker startup file is used to create linked units which use the full C mntime 
library and are to be configured using icconf . It also specifies a main entry point 
of c . ENTRYD, This is the main entry point of the standard C startup code for confi- 
gured systems using the full mntime library, c .ENTRYD is the first of a sequence 
of routines which are responsible for setting up the full version of the C runtime 
system and eventually calling the main function. The source of this startup code 
is supplied with this toolset and is described in the ANSI C Toolset Language and 
Ubrafies Reference Manual. 

cstartup . Ink includes clibs . Ink (see 3.11.4). cstartup . Ink should only 
be used if the configurer is also used. The effect of using this linker startup file to 
create a linked unit which is then passed directly to icollect, without using the 
configurer first, is undefined. It should only be used when the C linked unit created 
is to have access to host link channels. The startup code assumes that a server 
exists and will attempt to communicate with it. Thus the effect of its use in an envi- 
ronment where there is no access to the server is undefined. 

cs tartrd. Ink 

This linker indirect file is used to create linked units which use the reduced C 
runtime library and are to be configured using icconf. It also specifies a main 
entry point of c . entryd . RC. This is the main entry point of the standard C startup 
code for configured systems using the reduced runtime library, C. ENTRYD, RC is 
the first of a sequence of routines which are responsible for setting up the reduced 
version of the C mntime system and eventually calling the main function. The 
source of this startup code is supplied with this toolset and is described in the ANSI 
C Toolset Language and Libraries Reference Manual. 

cstartrd.lnk includes clibsrd.lnk (see 3.11.4). cstartrd.lnk should 
only be used if the configurer is aiso used. The effect of using this linker indirect 
fife to create a linked unit which is then passed directly to icollect, without using 
the configurer first, is undefined. It should be used in situations where the C linked 
unit created has or requires no access to the server. No host link channels are 
defined. 

cnonconf . Ink 

This linker indirect file is used to create linked units which use the full C runtime 
library and are suitable for passing directly to icollect thereby omitting the 
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configuration stage. Note: this method of program development is only applicable 
to singfe processor programs and is not recommended for any new program devel- 
opment as it may be unsupported in future toolsets. 

cnonconf . infc Specifies a main entry point of c . ENTRY. This is a special version 
of the C startup code which can derive for itself infomiation which is noimally 
supplied by the configurer {as such it is less efficient than the equivalent version 
of the startup code for configured systems and so use of the configurer is recom- 
mended). 

C . ENTRY is the first of a sequence of routines which are responsible for setting up 
the fuJI version of the C runtime system and eventually calling the main function, 
cnonconf .Ink includes clibs . Ink (see 3.11.4). cnonconf .Ink should only 
be used if the configuration stage is to be omitted. The effect of using this linker 
indirect file to create a linked unit which is subsequently passed to the configurer 
is undefined. It should only be used when the C linked unit created is to have 
access to host link channels. The startup code assumes that a server exists and 
will attempt to communicate with it. Thus the effect of its use in an environment 
where there is no access to the server is undefined. Indeed, omission of the config- 
uration stage is only possible if the full library is used, therefore there is no equiva- 
lent reduced version of this linker indirect file. 



3.11.2 Occam 2 Toolset 

For Occam, one of three linker indirect files should be selected according to the 
target transputer type{s) used, see table 3.5. 



Linker indirect file 


Target transputers 


oceam2 . Ink 


T212AT222yT225/M212 


occama , Ink 


T400AT41 4/T425n"426/TAATB 


occamS . Ink 


T800/T80iyT805 



Table 3,5 occam linker indirect files 

Each file contains a list of Occam library files which may be required to be linked, 
but which are additional to those explicitly referenced by the program. These 
include compiler libraries and support for interactive debugging. Depending on the 
other inputs and options specified on the command line the linker will select which 
libraries it requires from the supplied indirect file. 

3.11.3 Mixed language programs 

Mixed language programs require an appropriate linker indirect file for each 
language used. 

For Occam, one of the indirect files listed in table 3.5 Is always used and when the 
main program is written in C, one of the files listed in table 3.4 should be used. 
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However, if a non-C program calls in C modules, the standard C startup files are 
not suitable because they define a C main entry point which would conflict with the 
actual main entry point of the program. In this case one of the iinkerfiles described 
in section 3. 11 .4 should be used. These linkerfiles should also be used when incor- 
porating a C program into an Occam program as if it were an Occam process. 

Further information about mixed language programming Is given in Chapter 11. 

3.11.4 Other startup files supplied with the ANSI C Toolset 

Two additional linker indirect files are supplied with the ANSI C Toolset: 



Linker indirect file 


Comment 


clibs.lnk 


Lists the library files required for the full library. 


clibsrd.lnk 


Lists the library files required for the reduced library. 



Table 3.6 C linker indirect files referencing libraries only 

Unlike the files listed in table 3.4, cliba . Ink and clibsrd . ink do not specify 
a main entry point. They can be used whenever the main entry point of the program 
is not one of the standard C entry points, for example certain mixed language 
programs and when producing code which will be dynamically loaded. 

clibs . Ink should only be used when the C linked unit created is to have access 
to host link channels. The effect of using in an environment where there Is no 
access to the server Is undefined. 

clibsrd.lnk should be used in situations where the C linked unit created has 
or requires no access to the server. No host link channels are defined. 



3.12 Unsupported options 

A number of tools have various command line options beginning with 'Z'. These 
options are used by INMOS for development purposes and have not been 
designed for users. As such they are unsupported and should not be used. INMOS 
cannot guarantee the results obtained from such options nor their continued pres- 
ence in future toolset releases. 
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This chapter contains a tutorial that shows you how to compile, link, and run a 
simple example program on a single transputer. 

A more complex programming example illustrating separate compilation can be 
found in Chapter 5, together with a detailed description of program development 
for single processor systems. Chapter 6 provides examples of multitransputer 
programming. 



4.1 Introduction 

In order to create and run a transputer executable file, this sequence must be 
followed: 

1 The source files are compiled with the occam 2 compiler. The compifer 
creates from each source file an object file. 

2 The object files are linked together along with any libraries required, to 
create a file known as a linked unit. Each linked unit contains the code and 
data necessary to execute as a main program. 

3 The linked units are then configured onto a transputer nehworic and a boot- 
able program is created. In the case of a single program on a single trans- 
puter, there is a short cut available here. However, It is strongly recom- 
mended that development is made by using the full facilities of the 
configurer There are many advantages to this which will become apparent 
as the procedures are described. 

4 The program is then loaded and mn from the host by using the host file 
server. The bootable program contains everything necessary for execution 
on the transputer network and it will start automatically after it has been 
loaded. 



4.2 Running the examples 

In the following examples, the programs are complied and executed on a single 
T425 with 1Mbyte of memory available. If you have some other transputer, then 
you should make the necessary changes to the command lines and configuration 
file as indicated. (Command line options for specifying other transputer types are 
listed in appendix B of the occam 2 Toolset Reference Manual). 

The examples assume the existence of an environment variable TRANSPUTER 
which defines the name of a User Link on which to load the program, and that a 
connection database file exists to define that User Link, See the Delivery Manual 
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which accompanies this toolset and the iserver documentation (chapter 13 of 
the Occam 2 Toolset Reference Manual) for more details. 

The examples also assume the existence of the environment variables isearch, 
ICONDB, and IBOARDSIZE. See the DeAVe/y Want/a/ for details. 

The tutorial assumes that you have a boot from link board. If you have a boot from 
ROM board or other non-standard hardware, refer to the manufacturer's docu- 
mentation. 

4.2.1 Sources 

Source files are held in the toolset directory examples/manuals/sin^le. 

4.2.2 Example command lines 

In the examples below, the command lines are written in both the UNIX form with 
the option character ^-' ,and]nnon-UNIXfomi with the option character V^ (for 
MS-DOS and VAXA/MS systems). Choose the one that is applicable to you. 

4.2.3 Using the simulator 

If there is no transputer available, then you can use the simulator isim to mn the 
bootable program, provided it is built for a single T425. 

4.3 The example program 

The example program is contained in the file simple . occ. simple . occ reads 
a name from the keyboard and displays a greeting on the screen. The program 
uses the library hostio . lib and the include file hostio . inc. The configuration 
description resides in the file single. pgm. 

The program is illustrated below. 

fiNCLUDE "hostio, inc" — contains SP protocol 
PROC simple (CKAN OF SP fs, ts) 
#OSE ^'hostio.lib" 
[1000] BYTE buffer : 
BYTE result: 
INT length: 
SEQ 

so. write. string (fs, ts, 

"Please type your name :") 
so. read. echo. line (fs, ts^ length, buffer, 

result) 
so . write . nl ( f s , ts ) 
so. write. string (fs, ts, "Hello ") 
so.write.string.nl (fs, ts, 

[buffer FROM FOR length]) 
so, exit (fs, ts, sps. success) 
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The first line in the program loads the file hostio , inc. This file contains the defi- 
nition of protocol SP, used to communicate with the host file server, and a number 
of constants that are used in conjunction with the host i/o library. 

The procedure simple is then declared. All the working code is contained within 
this procedure. The server library hostio . lib Is referenced by the #USE direc- 
tive. This library contains all the procedures used by the program. See section 1 .5 
in the Occam 2 Toolset Language and Libraries Reference Manual for descrip- 
tions of the routines. 

Before the body of the procedure a number of variables are declared, buffer 
holds the input string, length refers to the number of characters in the name read 
from the keyboanj, and result is used by the library routine to indicate whether 
or not the read was successful. The result is Ignored by this example for the sake 
of simplicity; it is assumed that screen writes and keyboard reads always succeed. 
The working code is contained within a SEQ, indicating that the statements which 
follow are to be executed sequentially. All of the statements are calls to library 
routines in hostio . lib. The code prompts for a name, reads the name from the 
keyboard, and types a greeting on the screen. 

The last statement calls a library procedure which terminates the server, returning 
control to the host operating system. Without this statement the program would 
finish and appear to hang, and the server would have to be terminated explicitly 
by interrupting the program. 

4.3.1 Compiling the program 

In order to compile the program use the following command line: 

oc simple -t425 (UNIX) 

oc simple /t425 (MS-DOSA/MS) 

The compiler perfonns the necessary syntax, alias and usage checks, inserts code 
to perfomi runtime error checking, and creates a file called simple. tco. 
Because the source file has the default extension of . oec you can omit the exten- 
sion on the command line. 

The target processor is a T425. For information about compiling for other trans- 
puter types, see section 4.4. 

By default, the compiler enables interactive debugging with idebug and compiles 
the program in HALT mode (see section 5.3,1). 

4.3.2 Linking the program 

To use the result of your compilation it must be linked with the libraries that it uses. 

To link the program type: 

ilink simple, tco hostio. lib -t425 -f occama.lnlc (UNIX) 
ilink single . tco hostio . lib /t425 /f occama . Ink (MS-DOSA/MS) 
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This program uses hostio.lib and various target-specific compiler libraries. 
hostio.lib is directly specified on the command line; the correct compiler 
libraries are referenced via the 'f ' option (see below). 

Note: It is always good practice to specify to the linker what the transputer target 
\Sf since it is possible to produce code that can execute on a range of transputers 
and the linker must then be told which the actual target will be. In this example the 
chosen target is T425. 

The 'f option introduces a linker indirect We which is used to link in the correct 
compiler libraries. For more details see Chapter 9 In the Occam 2 Toolset Refer- 
ence Manual. 

The linked program will be written to the file simple, Iku. As no output file is 
specified, the file is named after the input file and the default link extension . iku 
is added. By default the program is linked in HALT mode. 

Note: In more complex programs, libraries may be dependent on other files and 
libraries. To ensure alf necessary libraries are linked Into a program, the imakef 
tool may be used v/ith a suitable MAKE program (see section 4.5). 

4.3,3 Configuring the program 

In order to configure the program, a description is required of the network it is run 
on. The file simple.pgm contains such a description. 

You should look at this file and edit it if it does not correspond to the hardware you 
actually have. For example check which link is connected to the host, the trans- 
puter type, and memory size. 

The file simple. pgm contains the following: 

NODE p ; 

ARC hostarc ; 

NETWORK 
DO 

SET p(type, merasize := "T425", 1024 * 1024) 
CONNECT p[lin]c] [0] TO HOST WITH hostarc 



#INCLUDE "hostio.inc" 
#USE "simple. Iku" 

CONFIG 

CHAN OF SP fs, ts : 
PLACE fs, ts ON hostarc 
PROCESSOR p 
simple (fsr ts} 
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In order to configure the application for the networ1<, the configurer is invoked as 
follows: 

occonf simple. pgm 

This produces a file called single . cfb which contains all the information about 
where the different parts of the program are to be placed. 



4.3.4 Collecting the program 

The final next stage is to collect all the parts of the program and combine them into 
a file which can be loaded onto the transputer for execution, This is done by the 
collector tool icollect. The collector is Invoked as follows: 

icolleet simple. cfb 

The result is the executable ('bootable') file sis^le .btl. 

4.3.5 Running the program on a transputer board 

To load the bootable program onto a transputer board and run it use the host file 
server tool iserver: 

iserver -se -sb siB^le.btl (UNIX) 

iserver /se /sb simple. btl (MS-DOSA/MS) 

The address of the transputer board is taken from the TRANSPUTER environment 
variable. 

The 'sb' option specifies the file to be booted and loads the program onto the trans- 
puter board. It has the effect of resetting the board, opening communication with 
the host, and loading the program onto the network. The 'se' option directs the 
server to temiinate if the program sets the en-orflag. For further information about 
server options see Chapter 13 in the Occam 2 Toolset Reference Manual. 

Figure 4.1 shows an example of the screen display obtained by running 
siiiiple .btl on a UNIX based toolset, for a user called 'John'. 



iserver -se -sb simple. btl 

Please type your name '.John 
Hello John 



Figure 4.1 Example output produced by mnning simple. btl 
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4.3.6 Running the program using isim 

To run the example program via the simulator use one of the following commands: 

isira -bq simple. btl (UNIX) 

isim /bq simple. btl (MS-DOSA/MS) 

The 'bq' option directs the simulator to run the program In 'batch quiet' mode, that 
is, run the program immediately and then terminate. For more information about 
the simulator tool see Chapter 14 in the Occam 2 Toolset Reference Manual. 

4.3.7 A short cut to creating a bootable fife 

For single-transputer programs booted from transputer links attached to a host, 
an altemative method can be used to create the . btl file. This method is not appli- 
cable to standalone systems nor to systems which boot from ROM, and requires 
the program to be contained within a single linked unit. The Advanced Toolset 
debugger cannot be used to debug programs created in this way. 

Note: Non-configured programs require a different procedural interface to confi- 
gured programs because certain parameters are expressed in the configuration 
description, simple . occ would therefore require the following change: 

replace: 

PROC simple (CHAN OF SP fs, ts} 
with: 

PROC simple (CHAN OF SP fs, ts, []INT memory) 

Single processor programs must always use a similar parameter list. A modified 
version of the program can be found in the examples directory under the name 
simpleS.occ. 

To make use of the shortcut, compile and link the siiDpleS , occ in the same way 
as in the previous example. Then, omitting the configurer stage, invoke the 
collector directly on the linked unit, adding the t option to the command line (the 
t option directs the collector to build a bootable file from a single linked unit): 

icollect simple3.1ku -t (UNIX) 

icollect simple3.1ku /t (MS-DOSAAMS) 

The bootable file sinLple3 . btl is created. This can be loaded and mn In the usual 
way using iserver or isim. 

Note: This facility acts as a compatibility mode with previous versions of the toolset 
and may be discontinued in future releases. 
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4.4 Compiling and linking for other transputer types 

If you are using a transputer other than a T425 you should specify the appropriate 
target transputer type for the compilation and linking operations. Appendix B in the 
Occam 2 Tooiset Reference Manual describes the options available. The same 
option must be specified to both the compiler, linketj and configurer, otherwise an 
error is reported. In addition, you must specify the correct linker indirect file forthe 
selected target, in order to link m the correct compiler libraries (see Chapter 9 of 
the Occam 2 Toolset Reference Manual). 

For example, to compile and link the program 'simple, occ' so that it will run on 
aTS00,T801orT805: 

UNIX: 

oc simple -tSOO 

ilink simple. tco hoatio.lib -f occamS.lnk -tSOO 

MS-DOSA/MS: 

oc simple /tSOO 

ilink simple. tco hostio.lib /f occamS.lnk: /tSOO 



Modify simple .pgm to match the transputer type and memory size of your hard- 
ware and run occonf on the modified file. Then collect and load the program as 
before. 



4.5 Using imakef 

As an alternative method of program development the toolset Makefile generator 
imakef can be used. This tool can produce a Makefile for any type of file that can 
be built with the toolset tools. See Chapter 11 in the Occam 2 Toolset Reference 
ManuaHor a description of the tool. 

imakef serves two purposes: 

• It enables the user to generate a target file automatically (e.g. a bootable 
file) without having to manually perform the intermediate stages of 
program development i.e. compiling, Unking, configuring etc. 

• For more complex programs, comprising several modules, it simplifies the 
incorporation of changes to the program by identifying dependencies and 
incorporating them into the Makefile. 

In order for imakef to be able to identify file types, a different system of file exten- 
sions must be used to that used in the examples above. See section 11.3 in the 
Occam 2 Toolset Reference Manual for a description of the system. 
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4.5 Using imalcef 



To create a Makefile for the configured simple program, use the following 
command: 

imakef simpleS.btl 

The ,btl extension directs imakef to build a bootable file from a configuration 
description file (simple2 . pgm). This file can be found in the examples directory. 
Within the .pgm file the correct fomat of file extension is used to reference the 
linked unit for imakef. For example: 

#USE '^simple. c5h" 

directs imakef to compile the program for a T425 in HALT enx)r mode. For other 
transputer types and error modes use different sufRxes, see section 11.3 In the 
Occam 2 Toolset Reference Manual. 

To build the program run your MAKE program on simple2 .mak: 

make -f simple2,mak (UNIX) 

make /f sin5>le2,mak (MS-DOSA/MS) 

This creates the bootable file sin5>le2 .btl which can be run in the normal way 
using iserver or isim. 
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transputers 

This chapter provides an introduction to occam programming on single trans- 
puters. For Information about programming multttransputer networi^s see 
Chapter 6. 

Before reading this chapter the user should already be familiar with the concepts 
and syntax of the occam programming language. A tutorial introduction to occam 
programming is a good introductory text and the Occam 2 Reference Manual 
contains a formal definition of the language. 

5.1 Program examples 

This chapter uses a relatively complex programming example (section 5.11), illus- 
trating separate compilation. A simple programming example, to get you started, 
is provided in Chapter 4. 

All the example programs are designed for boot from link boards, if you have a 
board that boots from ROM you should set it to boot from link or run the example 
programs using the T425 simulator tool isim. 

5-2 Occam programs 

Within the toolset a single processor pnDgram is a single occam procedure with 
a fixed pattern of fomial parameters, as illustrated below. 

fINCLUDE "hostio.inc" 

PROC occam. program (CHAN OF SP fa, ts, 
[ ] INT memory) 
body of program 



The procedure and its parameters can have any legal Occam names. You must 
always supply the procedure with the same type of fonnal parameters as shown 
above, to enable communication with the host and to enable the program to use 
free memory. The optional parameter stack .buffer may also be supplied; this 
allows the program to make use of the transputer's internal RAM (see sections 3.3 
and 3.4.2 in the Occam 2 Toolset Reference Manual). 

All occam procedures are terminated by a colon {: ), at the same indentation as 
the corresponding proc keyword. Do not forget the colon at the end of a program. 
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5.2 Occam programs 



Program input and output is supported by tlie host file server, which is resident on 
the host computer. Access to the host file server is via the i/o libraries, which are 
described m the Occam 2 Toolset Language and Ubranes Reference Manual. 
Whenever routines from these libraries are used the channels f s and ts must be 
passed to the routine so that it can communicate with the host file server. Channel 
f s comes from the host file server and ts goes to the host file server. Both use 
protocol SP, which is defined in the include file hostio. inc. Figure 5.1 shows 
how these channels are connected. 

The an-ay memory contains the free memory remaining on the transputer evalua- 
tion board after the program code has been loaded and the workspace allocated. 
It is calculated by subtracting the area occupied by the program code and data 
from the value specified in the iboapdsize host environment variable. The 
memory array is passed to the program as an an^ay of type INT, where It can be 
used. By allowing programs to be run on boards with different memory sizes, this 
array aids program portability between different boards. 
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Figure 5.1 Program input/output 

5.2.1 Compiling programs 

The compiler produces object code in TCOFF format for input to the linker. The 
compiler is capable of compiling code for any one of a range of transputers (the 
IMS T212, M212, T222, T225, T400, T414, T425, T426, T800, T801 orT805) in 
one of three error modes and with interactive debugging either enabled or 
disabled. The compiler enables interactive debugging by default unless the 
compiler 'Y' option is used- 
Transputer types and classes are described in Appendix B of the occam 2 Toolset 
Reference Manual. 

The standard error modes are HALT system and STOP process. A special mode, 
UNIVERSAL, enables code to be compiled so that it may be njn in either HALT or 
STOP mode. The target pnDcessor and en-or mode must be specified for each 
compilation, using options on the command line. 

By default the compiler compiles for an IMS T414 in HALT mode, and when 
compiling for this transputer type and en^or mode you may omit the options. In all 
other cases the options must be supplied. 
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Other operating features of the compiler may be changed by options and direc- 
tives. See Chapter 1 in the Occam 2 Toolset Reference Manual. 

If the compiler detects any errors, a source file name and line number is displayed 
along with an explanatory message and a portion of the source code surrounding 
the error. 

If the compilation succeeds, the compiler creates a new code file in the current 
directory. The filename for the new file is derived from the name of the source file 
and the default file extension . tco is added. The filename can also be specified 
on the command line. 

Compilation information 

It Is sometimes necessary to check how much workspace (data space) will be 
required to run the code. This information is stored in the code file produced by the 
compiler, linker and librarian. To display the information use the 'i' command line 
option or use the binary lister tool ili«t. For details of iliat see Chapter 10 in 
the Occam 2 Toolset Reference Manual. 



5.2^ Linking programs 

When all the component parts of a program have been compiled they must be 
linked together to form a whole program. Component parts include the main 
program, any separately compiled units, and any libraries used by the program, 
including the compiler tibraries. 

If required, the compiler libraries are automatically loaded by the compiler unless 
specifically disabled with the compiler 'E' option. If you are unsure whether your 
program uses the compiler libraries it is best to always link in the appropriate library 
anyway. Only library modules actually used by the compiled code will be included 
in the linked code file. The correct library for your program depends on the trans- 
puter type of the compilation. 

Three linker indirect files listing the compiler libraries are supplied for different 
transputer types. occaiii2 . Ink is provided for the T2 series, occama . Ink for the 
T8 series and occama. Ink for other 32-bit transputers. The relevant file should 
be included on the linker command line using the 'f option. For further details of 
the compiler libraries see the OCCam 2 Toolset Language and Libraries Reference 
Manual. 

By default, the order in which the code modules are specified on the command line 
determines their order within the linked unit; library modules being placed after the 
separately compiled modules. This default can be ovenuled by using the compiler 
directive #PRAGMA LINKilGE and the linkage directive #section (see sections 
1.12.7 and 9.4.6 in the occsm 2 Toolset Reference Manual). These directives 
enable the user to prioritize the order in which modules are linked together and so 
influence the use of on-chip RAM. 
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5,2.3 Displaying the contents of code files 

Object code files produced by compiling or linking programs can be examined 
using the binary lister tool ilist. Infonnation that can be displayed includes 
procedure definitions, exported names, extemal references within the code, and 
symbol data. For more details see Chapter 1 in the occam 2 Toolset Reference 
Manual. 



5.2.4 Making bootable programs 

Code that has been linked to form a program cannot be loaded directly onto a 
transputer evaluation board, for two reasons. Firstly, object code produced by the 
linker and compiler tools contains extra infonnation required by some tools. This 
information must be removed before the program can be loaded. Secondly, code 
to be run on a board which boots from link, such as the IMS B004, require the addi- 
tion of bootstrap information to load the program and start it running. 

Extraneous data is removed, and a boot-from-IInk bootstrap is added, by the 
collector tool icollect. 



5.2.5 Loading and running programs 

Bootable programs can be loaded onto the transputer evaluation boanj using the 
host file server iserver (see Chapter 13 in the Occam 2 Toolset Reference 
Manuaf). The server must be given a number of parameters when it loads a 
program. All server options are two characters long, with 'S' as the first character 
Server parameters are removed from the command line by the server, so you 
should avoid using the same options for your own program {it is best to avoid giving 
programs two letter options beginning with the letter 'S'>. 

To load a program use the 'SB' option and specify the file to be loaded. This has 
the same effect as using options 'SR\ 'ss', 'SI', and 'sc' together, that is, it resets 
the board, provides access to host facilities such as file access and terminal i/o, 
and loads the program. The 'SI ' option directs the tool to display progress informa- 
tion as it loads the file. To terminate when the transputer en-or flag is set, thereby 
enabling the program to be debugged, add the server *SE' option. 

Programs can also be loaded onto transputer networks, without using code on the 
root transputer, by first using the iskip tool to set up a skip process and then 
loading the program using iserver. This can be useful when loading programs 
onto external networks via a transputer evaluation board. It is also useful for 
debugging programs that normafly use the root transputer to run all or part of a 
program. The debugger always runs on the root transputer. Provided the network 
has at least one processor which is not used by the program, iskip may be used 
in conjunction with iserver to load the program over the root transputer. Further 
details can be found in the occafn 2 Toolset Reference Manual. 
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5.2.6 Interrupting programs 

To intenupt an applicaijon program while it is stilf running, press the host system 
BREAK key to interrupt the server. See the section entitled 'Server Intenxipts' in 
the Detivefy Manua! for the coned key to use on your system. 

When the BREAK key is pressed on DOS and VAX/VMS systems the following 
prompt fs displayed: 

(x) exit r (s) hell , or {c) ontinue? 

To abort the program t^^e 'x' or press | return | . This terminates the host file 
server 

To suspend the program so that you can resume it later, type 's'. 

To abort the interrupt and continue running the program, type 'c'. 



5.3 Occam error handling 

For systems that require maximum security and reliability, the en-or behavior is of 
great concern. OCCam 2 spedfies that run-time en-ors are to be handled in one 
of three ways, each suitable for dHferent programs. The error mode to be used is 
supplied as a parameter to both the compiler and linker. The options are listed in 
Table 5.1. 



Optfon(s) 


Description 


H 


HALT mode 


S 


STOP mode 


X 


UNIVERSAL mode 



Table 5.1 Compiler and linker options for selecting en'or mode 

5.3.1 Error modes 

The first mode, called Halt system mode or HALT mode, causes all run-time en-ors 
to bring the whole system to a halt promptly, ensuring that any en^nt part of the 
system is prevented from corrupting any other part of the system. This mode is 
extremely useliji for program debugging and is suitable for any system where an 
error is to be handled externally. HALT system mode is the default for the compiler, 
and you should use this mode when you may want to use the debugger. 

Note: on the IMS T414, T212, T222, and M212, HALT mode does not work for 
processes running at high prionty, as the HaltOnErrorflag is cleared when going 
to high priority. 

The second mode, called Stop process mode or STOP mode, allows more control 
and containment of en'ors than HALT mode. It maps all errant processes into the 
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process STOP, again ensuring that no errant process cxjrrupts any other part of 
the system. This has the effect of gradually propagating the STOP process 
throughout the system. This makes it possible for parts of the system to detect that 
another part has failed, for example, by the use ofwatchdog' timers. It allows multi- 
ply-redundant, or gracefully degrading systems, to be constructed. 

The third mode, called UNIVERSAL mode, may behave as either HALT or STOP 
mode depending on the transputer's Halt-On-En-or flag. For example if a library 
is compiled in UNIVERSAL mode, it may be linked in HALT mode with HALT mode 
modules and it will behave as if it had been compiled in HALT mode. Alternatively 
If It is lln ked in STOP mode with STOP mode modules it will behave as if it had been 
compiled in STOP mode. 

All separately compiled units for a single processor must be compiled and linked 
with compatible en-or modes. HALT and STOP modes are mutually exclusive 
whereas UNIVERSAL mode can be mixed wth either HALT or STOP. 

If no mode is specified the linker defaults to HALT mode; if the program contains 
STOP modules then an error is generated. Similarly, if STOP is specified on the 
command line the presence of HALT modules generates an em^r 

Where a library is used the module with the appropriate eror mode is selected by 
the compiler. 

Programs may also be compiled and linked in UNIVERSAL mode. This may be 
useful where linked modules are used as components of the final linked program 
- the error mode of the program can be postponed until the final link stage which 
builds the whole program. Programs built entirely in UNIVERSAL mode and 
targetted at single processors have their error mode set by the collector tool to Its 
default which is HALT mode. 

Table 5.2 summarizes error mode compatibility. 



Error mode 


Compatible with 


HALT 


HALT, UNIVERSAL 


STOP 


STOP. UNIVERSAL 


UNIVERSAL 


HALT, STOP, UNIVERSAL 



Table 5.2 Compatibility between error modes 
Error mode UNDEFINED 

The Occam en'or mode UNDEFINED can be reproduced by specitying the u 
command line option or the U argument to the #0PTI0N directive. 

5.3.2 Error detection 

In some circumstances it may be desirable to omit the mn time error checking in 
one part of a program, for example, in a time-critical sect'on of code^ while retaining 
error checks in other parts of a program, for debugging purposes. 
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The compiler provides three command fine options to enable the user to control 
the degree of run time error detection; they are the 'K', 'u' and Iia' options and they 
prevent the compiler from inserting code to explicitly perfomi run time checks. 

These options should only be used on code which is known to be correct. The 
compiler does not insert a lot of error checking code so it should only be disabled 
as a last resort. 

ft is the user's responsibility to ensure that errors cannot occur. The ability to 
disable certain error checking code by using the 'K' and 'D' options should not be 
abused in an attempt to use illegal code, since there is no way of telling the 
compiler to ignore alf errors. 

The *K' option disables the insertion of code to perform run time range checking. 
In this context the term range checking refers only to checks on array subscripting 
and an'ay lengths. Note: in any situation where the compiler can detect a range 
check error without specifically adding code, it may still do so. The type of situation 
where this is likely to happen is when an array subscript such as [i+f\ is used, and 
i+j overflows. 

The 'u' option disables the insertion of code whose onty purpose is to detect some 
kind of error. This option is stronger than the 'K' option, and includes the *K' option, 
so it is not necessary to use both options together. (Note: that the 'u' does not 
include the *NA' option which is described below). 

The "u' option will disable the insertion of run-time checks to detect occurrences 
such as the following: 

negative values in replicators 

erors in type conversion values, 

errors in the length of shift operations, 

array range errors, 

errors In replicated constructs such as SEQ, PAR, IF and ALT. 

Note: again in any situation where the compiler can detect an en"or without specifi- 
cally inserting code, it may still do so. Thus arithmetic overflows, etc, can still cause 
an en-or (To avoid overflow errors the operators PLUS, MINUS and TIMES can be 
used). 

If the 'u' option Is used in conjunction with HALT mode, it will prevent explicit 
checking for floating point en-ors in those cases where library calls are not used 
to perform floating point arithmetic (see below). In addition if the 'U' option is used 
with STOP or UNIVERSAL mode, it inhibits the ability of the system to gradually 
propagate a STOP process throughout the system. This means that the 'u' option^ 
when used w'rth any error mode produces Identical code. The object file, however, 
is still marked as being compiled in a particular en-or mode. 

Note: The 'U option can be used to optimize runtime perfomiance in code which 
is fully debugged and known to be error-free. This is equivalent to implementing 
UNDEFINED en-or mode. 
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Thus, faster code is produced by using the 'u' option with any error mode. Any 
libraries whicii are United with the modules will maintain the enor mode and level 
of error detection that they were compiled for. In practice, libraries compiled in 
HALT mode will be fastest, so for benchmarking, modu/es should be compiled in 
HALT mode and the 'u' option used. 

The 'HA' option disables the insertion of code to check calls to assert. 

The Occam 2 compiler recognizes a procedure assert with the following param- 
eter: 



PRDC ASSERT (VAL BOOL test) 

At compile time the compiler will check the value of test and if it is false the 
compiler will give a compile time error; if it is TRUE, the compiler does nothing. If 
test cannot be checked at compile-time then the compiler will insert a run-time 
check to detect its status. The 'na' option can be used to disable the insertion of 
this run-time check. 

5.4 Interactive debugging and virtual routing 

The compiler and linker tools support interactive debugging by default. When inter- 
active debugging is enabled the compiler or linker will generate calls to library 
routines to perform channel input and output rather than using the transputer's 
instructions. This does cause a performance penalty to be incurred when interac- 
tive debugging is enabled. Disabling interactive debugging by using the command 
line option 'Y' results in faster code execution. 

Interactive debugging must be enabled in order to use the interactive features of 
the debugger However, the debugger does not have to be present in order to run 
the code. 

Code which has interactive debugging disabled may call code which has interac- 
t've debugging enabled but not vice versa. If interactive debugging is disabled for 
any module in a program this will prevent the whole program from being debugged 
interactively. 

Disabling interactive debugging also disables virtual routing because both 
systems use the same set of routing and muftiplexing processes. 



5,5 Alias and usage checking 

The compiler implements the alias and usage checking njles described in the 
occsm 2 Reference Manual. Alias checking ensures that elements are not 
refen-ed to by more than one name within a section of code. Usage checking 
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ensures that channels are used con-ectly for unidirectionaf point-to-point commu- 
nication, and that variables are not altered while being shared beiWeen parallel 
processes. For a further discussion of the rationale behind these rules^ see 
Appendix C in the occam 2 Toolset Language and Libraries Reference Manual. 
Information is also given in the Transputer Applications Notebook - Arctiitecture 
and Software, Chapter 6 - The development of Occam 2. 

Alias and usage checking during compilation may be disabied by means of the 
compiler options 'A' and U'. Using the *N' option it is possfble to carry out alias 
checking without usage checking. However, it is not possible to perfomi usage 
checking without alias checking, as the usage checker relies on lack of aliasing in 
the program. Ifyou switch offaliaschecking with option 'A', usage checking is also 
disabled. 

The behavior of programs where alias and usage checks are disabled is defined 
in Appendix C of the occam 2 Toolset Language and Libraries Reference Manual. 

The 'K' and 'U' options will also disable the Insertion of alias checks that would 
otherwise be performed at mn-time. These options do not affect the insertion of 
alias checks at compile time nor the insertion of usage checks which are only 
performed at compile time. Alias checking can impose some code penalties, for 
example, extra code is inserted if array accesses are made which cannot be 
checked until runtime. The *W0' command line option will produce a waming 
message every time one of these checks is generated. However, aiias checking 
can also improve the quality of code produced, since the compiler can optimize the 
code if names in the program are known not to be aliased. 

The compiler usage check detects illegal usage of variables and channds, for 
example, attempting to assign to the same variable in parallel. The compiler 
performs most of its checks according to the mles defined in the occam 2 Refer- 
ence Manual, but with certain limitations. Normally, [f it is unable to implement a 
check exactly, it will perfomi a stricter check. For example, if an an-ay element is 
assigned to, and its subscript cannot t>e evaluated at compile time, then the 
compiler assumes that all elements of the array are assigned to. 

If a con-ect program is rejected because the compiler is imposing too strict a rule, 
it is possible to switch off usage checking, either on the command line forthe entire 
compilation, or by a pragma for a specific variable. 

It should also be noted that usage checking can slow the compiler down. For 
example, programs which contain replicated constructs defined with constant 
values for the base and count, will be checked for each iteration of the routine. 
Replicated constructs which have variable base and count values are only 
checked once with a stricter check, because the compiler cannot evaluate, at this 
point, the actual limits of the replication. 
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5.6 Using separate vector space 

The compiler normally produces code which uses separate vector space. Arrays 
which are declared within a compilation unit are allocated into a separate Vector 
space' area of memory, rather than into workspace^ when they are > 8 bytes. 

This decreases the amount of stack required, which has two benefits: firstly, the 
offsets of variables are smaller, access to them is faster; secondly, the total amount 
of stack used is smaller, allowing better use to be made of on-chip RAM. 

The compiler option V disables the use of a separate vector space, in which case 
arrays are placed in the workspace. 

When a program is loaded onto a transputer in a networit, memory is allocated 
contiguously, as shown in Figure 5.2. 



#80000000 




MOSTNEG INT 
+ IBQAHDSIZE 

Memfltart 
MOSTNEG INT 


Unallocated memory 

(passed as parameter 

to program) 


Occam vector space 


Occam code 


Occam workspace 


Reserved by transputer 





Figure 5.2 Memory allocation on a 32-blt transputer 

This a Hows the workspace (and possibly some of the code) to be given priority use 
of the on-chip RAM, Generally, the best perfonnance will be obtained with the 
separate vector space enabled. 
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The default allocation of an array can be ovenidden by an allocation immediately 
after the declaration of an an^ay. This aliocation has one of the forms: 

PIJICE name in vecspace : 

PLACE name IN WORKSPACE : 

(Note: the PLACE statement must be inserted immediately following the declara- 
tion of the variable to which it refers). 

For example, in a program which is normalfy using the separate vector space, it 
may be advantageous to put an important buffer into workspace, so that it is more 
likely to be put into internal RAM. The program would be compiled with separate 
vector space enabled^ but would include something like: 



[buff .size] BYTE crucial . buff er : 
PLACE crucial. buffer IN WORKSPACE 



For a program where it is required to put all of the data apart from one large an^y 
into the workspace, the program would be compiled with separate vector space 
disabled, and the array allocated to vector space by a place statement such as 
PLACE large, array IN VECSPACE. 

Within a program it is possible to mix code compiled with separate vector space 
on and code compiled with separate vector space off. The parts of the program 
which have been compiled with separate vector space enabled vAW be given use 
of the vector space. 

Note that certain libraries such as hostio.iib use vector space. Therefore, it 
is likely that some use ofvector space will be made, even if vector space Is disabled 
for a program module. 

5.7 Sharing source between files 

The source of a program can be split over any number of files by using the 
#INCLUDE directive. This directive enables the user to specify a file which contains 
Occam source. The contents of this file are included in the soun^e at the same 
point and with the same Indentation as the #INCLUDE directive. Include files may 
be nested to any depth - the compiler does not impose a limit. By convention, the 
, inc file extension is used for OCCam constant and protocol definitions. An 
example of using the #INCLUD£ directive is given below: 

#INCLUDE "infile-inc" — source in infile.inc 



The name of the file to be included is placed in quotes. All of the line following the 
closing quote may be used as for comments. All directives occupy a single line. 
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5.8 Separate compilation 

Separate compilation reflects the hierarchical structure of Occam, and the 
Occam compiler compifes occam procedures and/or functions (procs and 
functions). Any number of procedures and/or functions may be compiled at any 
time, provided the only extemal references they make are via their parameter lists. 

A group of procedures and/or functions that are compiled together are known as 
a compilation unit. Each procedure and/or function in such a group may be called 
intemaify by other procedures declared later in that group, or externally by any 
Occam in the scope of the directive which references that separate compilation 
unit. Constant declarations and protocols are also permitted inside a compilation 
unit, for the use of the procedures and functions within it. The scope of a separate 
compilation unit is the same as any normal OCCam procedure or function. 

Separately compiled units are referenced from Occam source as object code files, 
using the #USE directive. The object file may be a compiled (.tco) or library 
( , lib) file. If the file extension is omitted the compiler adds the extension of the 
cun^nt output file. This will be (.tco) unless an output fUe has been specified 
using the '0' option. 

An example of how to reference a separately compiled unit is shown below. 
#USE "3cunit,tco" — code in file scunit.tco 



The filename must be enclosed in double quotes. Afl of the line following the 
closing quote can be used as comment. The directive must occupy a single line. 

Separate compilation units may be nested to any depth and may contain 
#INCLUDE directives. They may also use libraries, as described in section 5.10, 
A separate compilation unit must be compiled before the source which references 
it can be compiled. 



5.8.1 Sharing protocols and constants 

occam constants and protocols may be declared and used within a compilation 
unit according to the mies of the language. Where a constant and/or protocol is 
to be used across separate compilation boundaries, it should always be placed in 
a separate file. The file should be referenced in any compilation unit where it is 
needed, by using the #include directive before any #US£ directive, which 
introduces pnijcedures using the protocol in their formal parameter lists. Protocols 
will also need to be referenced in any enclosing compilation unit (because the 
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channels will either be dedared there or passed through). For example, suppose 
we have a protcxxsl p defined in afilemyprot . inc. We might then use it as follows: 

PROC mainO 

#INCLDDE "myprot.inc" 
#USE "mysctco'' 

CEAK OF P actual. chzmnel : 
PAR 

do . it (actual . channel) 



The separately compiled procedure do . it, in the file mysc . occ, would look like 
this: 



#INCLUDE "myprot . inc'^ — declares protocol P 
PROC do.it (CHAN OF P in) 

SEQ 

. . . body of procedure 



Since the protocol name P occurs in the formal parameter list of the separately 
compiled procedure do.it, the compilation unit must include a #ikclude direc- 
tive, preceding the declaration of do . it, to introduce the name P. 

5.8.2 Compiling and linking large programs 

Building a pn^gram which includes separate compilation units and library refer- 
ences is straightforward. Separate compilatk>n units in the program can be 
compiled individually by applying the compiler to them. Nested compilation units 
must be compiled in a bottom<up order before the top level of the program is 
compiled; finally the whole program is linked together. 

Separate compilation units must be compiled before the unit which references 
them can be compiled. This is because the object code contains all the information 
about a unit (names, formal parameters, workspace and code size, etc) which is 
needed to arrange the static allocation of workspace and to check correctness 
across compilation boundaries. This infomiation may be viewed using the ilist 
tool. 

When a program is linked the code for all the separate compilation units In the 
program Is copied into a single file. In addition, code for any libraries used Is 
included in the f)le. Where libraries contain more than one module, only those 
modules containing routines actually required in a program are linked into the final 
code. This helps to minimize the size of the linked code. 
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The target processor or transputer class and error mode must be specified to the 
linker to enable it to select appropriate library modules. Only one processor type 
or class may be used for the linking process and this must be compatible Nvith the 
transputer type or class used to compile the modules. The error mode used for the 
linking process must also be compatible with the en'or mode(s) used to compile 
the modules. Compatible use of the compiler and linker 'Y' option must also be 
adopted for the modules to be linked. 

If there are a large number of input modules, they may be supplied to the linker 
within an indirect file, as a list of filenames. Indirect files may also contain directives 
to the linker. Linker directives enable the user to customize the linkage operation, 
e.g. define aliases, symbols, and references, modify the ordering of modules, and 
include other indirect files. Section 9.4 in the Occam 2 Toofset Reference Manual 
describes the operation of linker directives. 



5.9 Using imakef 

When a change is made to part of a program it is necessary to recompile the 
program to create a new code file reflecting the change. The purpose of the sepa- 
rate compiiation system is to split up a program so that only those parts of the 
program which have changed or which depend on the changed units, need to be 
recompiled, rather than needing to recompile the whoie program. However, it 
would be tedious to have to remember which modules had been edited, which 
modules might be affected by calls and the order in which the modules were 
compiled and linked. For this reason a Makefile generator imakef is supplied with 
the toolset and may be used to assist with building programs consisting of several 
modules. This tool, when applied to a program (or part of a program), compiles a 
list of dependencies of compilation units and uses this list to produce a Makefile. 
The Makefile can be used with a suitable MAKE program to recomplEe only the 
changed parts of a program. This ensures that compilation units will always be 
recompiled where a change has made this necessary. 

To use the Makefile generator you must tell It the name of the file you wish to build. 
The tool can produce a Makefile for any type of file that can be built with the toolset 
tools. In order for imakef to be able to identify file types, a different system of file 
extensions must be used to that used in this chapter. The filename njles for 
imakef are described in section 11 .3 of the Occam 2 Toolset Reference Manual. 



5.10 Libraries 

A library is a collection of compiled procedures and/or functions. Any number of 
separately compiled units may be made into a librafy by using the librarian. Sepa- 
rately compiled units and libraries can be added to existing libraries. Each compila- 
tion unit is treated as a separately loadable module within a library. When compiling 
or linking, only modules which are used by a program are loaded. The rules for 
selective loading are described in the following section. 
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Libraries are referenced from occam source by the #use directive. For example: 

#USE ''hostio.lib" — host server library 

The filename is enclosed in quotes. The rest of the line, following the closing quote, 
may be used for comments. Directives must occupy a single line. 

Libraries should always use a .lib file extension, and this must always be 
supplied in a #USE directive. 



5.10.1 Selective loading 

Each module {separately compiled unit) in a library is selectively loadable by the 
linker; i.e. parts of a library not used or unusable by a program are ignored. The 
unit of selectivity is the library module; i.e, if one procedure or function of a library 
module is used then all the code for that module is loaded. 

The compiler is selective when a library is referenced. Only modules of a library 
that are of the same, or compatible, transputer type or class, error mode and 
method of channel input/output, are read (see Appendix B in the Occam 2 Toolset 
Reference Manual, and sections 5.3 and 5.4 in this chapter). 

Selective loading is based on the following rules: 

1 The transputer type or class of a library module must be the same as, or 
compatible with, the code which coutd use it. 

2 The error mode of the library module must be the same as, or compatible 
with, the code which could use it. 

3 The interactive debugging mode (i.e. whether interactive debugging is 
enabled or not) of the library must be the same, or compatible with, the 
code which could use it. 

4 At least one nsutlne (entry point) in a module is called by the code. 

Rules 1 to 3 apply to the compiler. All the rules are used by the linker. The compiler 
only selects on transputer type, error mode and method of channel input/output. 
It is not until the linking stage that unused modules are rejected. For details on 
mixing processor classes see Appendix B in the Occam 2 Toolset Reference 
Manual, and for information on mixing error modes see section 5.3. 



5.10.2 Building libraries 

Libraries are built using the librarian tool ilibr. Libraries can be created from 
either separately compiled units (. tco or library files . lib) or from linked units 
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( . Iku files) but not a combination of botii. The librarian takes any number of input 
files and combines them into a single library file. Each separately complied unit 
forms a single module in the library. 

When forming a library the librarian will warn if there are multiply defined routines 
(entry points). In other words, for each combination of transputer type, error mode 
and method of channel input/output there may only be one routine with a particular 
name. Forftirther information on building and optimizing libraries see Chapter 8 of 
the Occam 2 Toolset Reference Manual. 

As an example consider building a library called mylib, lib. The source of this 
library is contained in a file called mylib. occ and has been written to be compil- 
able for both 16 and 32 bit transputers. We want the library to be available forT212 
and T800 processors in halt on error mode only. Having compiled the source for 
the two processors we will have two files, for example: mylib. t2h and 
mylib. tSh. To form a library from these compilation units use the following 
command line: 



ilibr mylib, t;2h mylib. tSh 

When an output filename is not specified, as in this example, the librarian uses the 
first file in the list to make up the output file name and adds the extension . lib. 
In this case it will write the library to the file mylib. lib. 

The librarian can also take an indirectfile containing a list of the files to be built into 
the library. Such files should have the same name as the library, but with a . Ibb 
file extension. So, still using the above example, if the names of the files to make 
up the library were put in a file called mylib . Ibb, we could then build the library 
using one of the following commands: 

ilibr -f mylib. Ibb -o mylib. lib (UNIX) 

ilibr /f mylib. Ibb /o mylib. lib (MS-DOSA/MS) 

Compiled modules can be added to an existing library file. However, if the librarian 
attempts to create an outputfile with the same name as an input libraryfile, an error 
will be produced. This can be avoided by specifying a different output filename 
using the '0' option. Alternatively if one on the compiled modules to be added to 
the library has a different name, this could be specified first on the command line. 
Once the new libraryfile has been created it can be renamed if necessary. Adding 
modules to an existing library does not require programs which call it to be recom- 
piled, provided it is given its original name in its final form. 

The Makefile generator imakef can be used to assist with the building of libraries. 
This is particulariy useful where libraries are nested within other libraries or 
compilation units, because imalcef can identity the dependencies of libraries on 
other modules or separately compiled units. For further information about the 
imakef tool see Chapter 11 of the Occam 2 Toolset Reference Manual. 
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5.11 Example progrann - the pipeline sorter 

This section tnlroduces an example which serves to show how a large program 
might be structured, in terms of separate compilation units, libraries, and a shared 
protocol, Occam source files, header files, and the configuration description for 
this program, can be found on the examples/ sorter directory. 

5,11,1 Overview of the program 

The program sorts a series of characters into the orderof their ASCII code values. 




Figure 5.3 Basic structure of sorter program 

Figure 5.3 shows the basic structure of this program. There are three processes: 
the input process, the output process and ^e sorter process. We can decompose 
the sorter process by using a pipeline structure. This uses the algorithm described 
in A tuioriai introduction to OCCam programming. If we design the pipeline carefully 
we can ensure that each element of the pipeline is identical to al[ the other 
elements. The pipeline is served by an input process, which reads characters from 
the keyboard, and an output process which writes the sorted characters to the 
screen. Figure 5.4 shows the structure of the program using a pipeline. 



( \HPUT ]-4 element )—{ element V 




Figure 5.4 Pipeline of n elements 

An obvious implementation would be to write an Occam process for each process 
in Figure 5.4^ using a replicated process for the pipeline. Communication between 
the processes is via Occam channels and to aid program con'ectness we should 
use an Occam protocol for these channels. This protocol must be shared by 
all the processes. As the Occam compiler compiles processes (PROCs) and as 
each of the processes is independent we can implement each one as a separately 
compiled unit. The processes share a common protocoi and the best way to 
ensure consistency is to place the protocol in a separate file and use the 
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flNCLUDE mechanism to access it. These processes can then be called In parallel 
by an enclosing program which can access the code of each process by the #USE 
mechanism. 

There is a problem with this implementation because two processes require 
access to the host file server. The host file server is accessed via a pair of occam 
channels and occam does not allow the sharing of channels between processes. 
There are a number of ways around this problem. One solution is to use a multi- 
plexor process for the server channels^ as described in section 8.5. Another solu- 
tion is to merge the two processes into a single process. This solution is used 
because the program accesses the server in a sequential manner (read a line then 
dispEay sorted line, read a line etc.). Figure 5.5 gives the final process diagram for 
the program. 




Figure 5.5 Program with combined input/output process 
The implementation can be split functionally into four files: 



element. occ 
inout . occ 
sorter. occ 
sorthdr.inc 



the pipeline sorting element 
the input/output process 
the enclosing program 
the common protocol definition 



Figure 5.6 shows the way these files are connected together to form a program. 
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Figure 5,6 file stnjcUjre of program 

The source of the pnagram is given below and is supplied in the 'examples' direc- 
tory. You can either copy these files to a working directory or you can type in the 
source as given below. 

Two otherfiles are required to complete the program . These are the host file server 
library hostio.lib and the corresponding .inc file containing the host file 
server constants. These are automatically referenced using the isearch environ- 
ment variable. 



5.11.2 The channel protocol 

Declarations of constants and channel protocols are contained in the include file 
sorthdr .inc, which is listed below. 

PROTOCOL LETTERS 
CASE 

letter; BYTE 
end . of . letters 
terminate 



VAL number . elements IS 100: 



upper bound 



This declares a protocol called letters, which pennits three different types of 
message to be communicated: 
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letter - followed by the character to be sorted, 

end , of . letters - marks the end of the sequence to be sorted, 
terminate - signals the end of the program. 

The constant number, elements Is also declared. This defines both the number 
of sorting elements in the pipeline and the maximum length of the sequence of 
characters that can be sorted. 

5,11 .3 The sorting element 

The sorting element element, occ is listed below: 

#INCLUDE "sorthdr.inc'^ 

PROC sort. element (CHAN OF LETTERS inputs output) 
BYTE highest: 
BOOL going: 
SEQ 

going := TRUE 
WHILE going 
input ? CASE 
terminate 

going := FALSE 
letter; highest 
BYTE next: 
BOOL inline; 
SEQ 

inline := TRUE 
WHILE inline 
input ? CASE 
letter; next 
IF 

next > highest 
SEQ 

output ! letter; highest 
highest := next 
TRUE 

output ! letter ; next 
end. of .letters 
SEQ 

inline := FALSE 
output ! letter; highest 
output \ end. of .letters 
output ! terminate 

This program consists of two loops, one nested inside the other. The outer loop 
accepts either a tenrtination signal or a character sequence for sorting. If it 
receives a character it enters the inner loop. The inner loop reads characters until 
it receives an 'end of letters' signal, signifying the end of the string of characters 
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to be sorted. The sort is performed by storing the highest (ASCil) value character 
it recefves and passing any lesser (or equal) characters on to the next process. The 
'end of fetters' lag causes the stored value to be passed on and tlie inner loop 
temiinates. 

The maximum number of characters which can be sorted is determined by the 
number of sorter processes. One character is sorted per process. 



5.11.4 The input/output process 

This process consists of a loop which reads a line from the keyboard, then sends 
the line to the sorter and, in parallel, reads the sorted line back. It then displays the 
sorted line. If the line read from the keyboard is empty the loop is temiinated. At 
the end of the process the host file sefver is terminated with the success constant 
sps . success, which is defined in the file hostio . inc. 

If any i/o errors occur the program will stop, allowing it to be examined by the 
debugger. 

The input/output process inout.occ Is listed below. 

#INCLDDE "sorthdr.inc" 

tINCLDDE "hostio. inc" 

PROC inout (CHAN OF SP fs, ts, 

CHAK OF LETTERS from. pipe, to. pipe) 
#DSE "hostio, lib" 

[nujnber, elements * 1]BYTE line, sorted, line: 
INT line. length, sorted. length: 
BYTE result: 
BOOL going: 
SEQ 

so. write. string, nl (fs, ts, 
"Enter lines of text to be sorted * 
*- empty line terminates") 
going := TRUE 
WHILE going 
SEQ 

so . read . echo . line ( f s , ts ^ line . length , 

line, result) 
IP 

result <> spr.ok 

STOP — stop if an error occurs 
TRUE 

so.vrite.nl (fs, ts) 
PAR 
SEQ 
IF 

(line. length = 0) 
to . pipe ! terminate 
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TRUE 
SEQ 

SEQ i = FOR line, length 

to. pipe ! letter; line[i] 
to. pipe ? end. of .letters 
BOOL end. of. line: 
SEO 

end, of. line := FALSE 
sorted. length := 
WHILE NOT end. of, line 
from. pipe ? CASE 
terminate 
SEQ 

end. of. line :^ TRUE 
going :- FALSE 
letter ; sorted . line [ sorted . length] 

sorted. length := sorted. length + 1 
end. of .letters 
SEQ 

so. write. string.nl (fSf ts, 
[sorted. line FROM 
FOR sorted. length]) 
end, of. line := TRUE 
so, exit (fs, ts, sps. success) — terminate server 



5.11.5 The calling program 

This process calls the input output process in parallel with the sorter elements, in 
a pipeline. The memory parameter must be declared, but the program does not 
use it. 

The calling program sorter .occ is listed below. 



#INCLUDE ''hostio.inc" — 

PROC sorter (CHAN OF SP fs, ts , []INT meaory) 

#USE "hostio.lib" 

#INCLUDE "sorthdr.inc" — 

#USE '^inout" 

#USE "element" 

[number. elements + 1]CHAN OF LETTERS pipe; 
PAR 

inout(fs, ts, pipe [number. elements] , pipe[OJ) 

PAR i = FOR number , elements 
sort. element (pipe [i] , pipe[i+l]) 
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5.11.6 Compiling the program 

To build the program, first compile each component of the program separately, link 
them together, and add bootstrap code to the main compilation unit. 

The program's components must be compiled in a bottom up fashion, that is, 
element . occ and inout.occ first {in either sequence), followed by the main 
program sorter.occ. First, compile the sorting element element. occ using 
one of the following commands: 

oc element -t425 (UNIX) 

oc element /t425 (MS-DOSA/MS) 

The file extension can be omitted on the command line because the source file has 
the conventional extension .occ. The compiler produces a file called 
element . teo, compiled for a T425 In HALT mode. 

Next compile the input/output process using the following command; 

oc inout -t425 (UNIX) 

oc inout /t425 (MS-DOSA/MS) 

The compiler produces a file called inout . tco, compiled for a T425 in the default 
HALT error mode. 

Finally compile the main body using the command line: 

oc sorter -t425 (UNIX) 

oc sorter /t425 (MS-DOSA/MS) 

The compiler produces a file called sorter . tco, compiled for a T425 in HALT 
mode. 

5.11.7 Linking the program 

Having compiled all the components of the program you can now link them 
togethertofomiawhole program. Any libraries used by the program must also be 
specified to the linker. The library hostio . lib is the server library used by this 
program. Remember the include file, occama.lnk, which identifies the other 
libraries, such as compiler libraries, required in the linking process (see section 
3.11.2). 

To link the files use one of the following commands: 

ilink sorter. tco inout. tco eleEoent.tco hostio. lib -f occama.lnk -t425 

(UNIX) 

ilinfc sorter. tco inout. teo element. tco hostio. lib /f occama.lnk /t425 

(MS-DOS/VMS) 
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The linker will create the file sorter . iku linked for a T425 in HALT mode. 

If a main entry point is not specified, the linker uses the first valid entry point that 
it encounters in the input. Therefore, in the above example, it is important to list 
the file 'sorter . tco' first. A main entry point may be specified within an indirect 
file using the linker directive #mainentry or on the command line using the linker 
'ME' option. 

5.11,8 Configuring and coltecting the program 

Before you can mn the program you must configure and collect the program. This 
will generate a bootable file which can be loaded and run using iserver orisim. 
Use the following sequence of commands: 

occonf sorter. pgm 

icollect sorter. cfb 

occonf generates the file sorter . cfb which is then processed by the collector 
tool This creates the bootable file sorter .btl. 

sorter. pgm configures the program for a single IMS T425 with 1Mbyte of 
memory; this should be checked against your own hardware and modified if neces- 
sary: 

NODE p ; 

ARC ho stare ; 

NETWORK 
DO 

SET pCtype, memsize := "T425", 1024 * 1024) 
CONNECT p[link] [0] TO HOST WITH hostarc 



tINCLUDE "hostio-inc" 
#USE "sorter. iku" 

CONFIG 

CHAN OF SP fs, ts : 
PLACE fs, ts ON hostarc ; 
PROCESSOR p 

[ 1 ] INT dtumny . memory : 
sorter ( f s , ts , dijinniy . memory) 



5.11.9 Running the program 

The bootable file can be run using iserver or isim. To load the program onto 
a transputer board use one of the following commands: 

iserver -se -sb sorter, btl (UNIX) 

iserver /se /sb sorter, btl (MS-DOSA^MS) 
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The 'sb' option specifies the file to be booted a nd loads the program onto the trans- 
puter board. It has the effect of resetting the board, opening communication with 
the host, and loading the program onto the network. The 'se' option directs the 
server to terminate rf the program sets the error flag. For more details about 
running the iserver see Chapter 13 in the Occam 2 Toolset Reference Manual. 

The program reads characters from the keyboard, sorts the line and redisplays [t. 
The program will run until input is terminated by typing RETURN on an empty tine. 

Figure 5.7 shows an example of the screen display obtained by njnning 
sorter, btl on a UNIX based toolset. The user inputs the string 'Sorter program" 
and terminates the program by pressing RETURN. 



iserver -se -sb sorter. btl 

Enter lines of text to b« sorted - ett5>ty line terminates 
Sorter program 
Saegmooprrrrt 



Figure 5.7 Example output produced by running sorter. btl 

To run the program using isim use one of the following commands: 

isim -bq sorter. btl (UNIX) 

isim /bq sorter. btl (MS-DOSA/MS) 

The 'bq' option specifies batch quiet mode which causes the simulator to run the 
program and then tenninate. For a description of the simulator tool see Chapter 
14 in the Occam 2 Toolset Reference Manual. 

5.11.10 Alternative method of creating a bootable file 

Because the program is to be toaded on a single transputer, a shortcut may be 
used (see section 4.3.7). The bootable file can be created directly from the linked 
unit using the collector 't' option, omitting the configurer stage: 

icollect sorter. Iku -t (UNIX) 

icollect sorter. Iku /t (MS-DOSA/MS) 

The 't' option informs the collector that the input file is a linked unit rather than the 
output of the configurer tooL If this method is used, the collector creates as a 
by-product a .cfb file, redundant in this example. 

As in the configured case the collector creates the bootable file sorter, btl 
which can be loaded and mn using iserver or isim. 
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5.11.11 Automated program building 

The imakef tool can be used to automate the development process. From the 
above example it can be seen that there are many steps to go tiirough when 
building a program of any size. Some of these steps must be performed in a 
specific order and if part of the program were changed then all affected parts must 
be recompiled and relinked etc. 

MAKE IS a common tool for building programs. It uses infomiation about when files 
were last updated, and perfomis all the necessary operations to keep object and 
bootable files up to date vwth changes in any part of the source. Makefiles are the 
standard method of providing the MAKE program with the information it needs. 

The Occam toolset is designed in such a way that it is possible for a tool to 
construct Makefifes to bufid occam programs. The Makefile generator imakef 
produces Makefiles in a fonmat acceptable to most MAKE programs. 

imakef requires the user to adopt a particular convention of file extensions. The 
user then only has to specity the target file s/he requires i.e. a bootable file and 
imakef, ustng its knowledge of file names mles, creates a suitable Makefile. This 
file has full instructions on howto build the program. By running the MAKE program 
for the fi[e the entire program wi[l be automatically complied, linked and made boot- 
able, ready for loading onto the transputer 

For more details about the imakef tool and an example of how to create a make- 
file for the pipeline sorter program used in this chapter, see Chapter 11 In the 
Occam 2 Toolset Reference Manual. 
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This chapter describes how to build programs that run on networks of transputers. 
It describes how to configure an occam program for a network of transputers 
using the configuration language and the Occam configurer tool occonf , illus- 
trated with an example program for four transputers. The chapter also includes 
examples illustrating various aspects of configuration. 



6.1 Introduction 

In order to build programs for multitransputer networks a program is split into a 
number of self contained components, and each of these is implemented as an 
Occam process. Each process may communicate with other processes resident 
on the same transputer or, via links, with processes on other transputers. 

Programs consisting of Occam processes can be mn on single or multiple trans- 
puters, in any combination. Performance requirements can be met by adapting the 
application to run on differing numbers of transputers, and by using differing 
network topologies. 

The mapping of processes to processors on a transputer networit is known as 
configuration. Transputer programs can be configured to run on any physical 
network of transputers. They can be loaded from an extemal host down a trans- 
puter link, or loaded from ROM. 

Configuration is achieved by writing a configuration description in the Occam 
configuration language. A configuration description is created by the user as a text 
file which is processed by the configurer tool to generate a configuration data file. 
This data file is in turn processed by the collector tool icollect to generate a 
transputer loadable file. 

Within a configuration description the hardware networic and the software descrip- 
tion are kept separate. This enables the software description to be used for running 
the same parallel program on a variety of alternative hardware networks. Likewise 
a particular physical network may be described once for use in a variety of configu- 
rations describing different programs that may be run on the same network. 

6.1.1 Mixing languages 

By using the facilities for calling other languages from Occam, programs compiled 
from mixed language sources may also be configured using the occam confi- 
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gurer. (These facilities enable the foreign language code to be incorporated into 
the Occam program as equivalent occam processes. An example of this is 
provided in the user exan^les directory supplied with the toolset. A description 
of this method of mixed language programming is given in Chapter 11). Similarly 
it is possible to configure occam modules which are called by C programs using 
the configurer provided with the ANSI C toolset. Details of bow to do this are given 
in the ANSI C Toolset User Guide. 



6.2 Configuration model 

The configuration model consists of the following parts: 

• A hardware network description which declares a network as a connected 
graph of processors. 

• A software description in the form of an Occam process. 

• A mapping between the processes and channels of the software and the 
nodes (processors) and arcs (transputer link connections) of the network. 
The mapping is achieved by declaring names and, in the scopes of these 
declarations, refening to the names in the structures of the configuration 
description. Normal OCCam scope mles apply. 

The software description takes the form of an occann process with at least as 
many parallel sub-processes as there are hardware processors in the networic. 
Within the description, each process which may be independently placed on a 
processor, is introduced by a processor construct naming a processor. Proces- 
sors so named may either be the hardware processors declared In the network 
description, or may be logical processors mapped onto the hardware processors 
fn a separate mapping structure. In either case the processor name must have 
appeared in a NODE declaration in whose scope the software description is written. 

The connections between processes in the software description are defined by 
occann channels. It is thus possible forthe configurer tool to determine what code 
is to be loaded onto what processor, and to choose its own mapping of channels 
onto physical connections between processors. 

Some channels may be used to connect to hardware outside the networic, such 
as the development host or other hardware connected by means of link adaptors. 
External objects of this kind are declared as EDGES in the hardware description. 

All processors which are connected together are connected via their links, repre- 
sented in the language as attributes, of type edge, of declared nodes. 

The connections to external edges, or those between processors, may optionally 
be declared as arcs, which associate a name with a particular connection. This 
enables explicit mappings of channels onto these arcs to be made. 
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6.2.1 Configuration language 

A configuration description consists of a sequence of dedaratlons and statements. 
The language used is an extension to occam and follow the usual Occam scape 
rules - in fact, the (X)nfigurer uses the oocam compiler to evaluate these state- 
ments. Appendix A defines the syntax of the Occam configuration language. 

Configuration declarations introduce physical processors, arcs and edges of the 
networit, network connections and processor attributes, logical pnxessors to be 
mapped onto physical processors, the software description, and the mapping 
between logical and physical processors. These are listed in Table 6.1. 



Declaration 


Description 


NODE 


Introduces processors {nodes of a graph). These processors 
are considered to be p/jys/ca/ if they are defined as part of the 
hardware description, or /og/ca/ if they are defined as part of 
the software description and mapped to a physical processor 
as part of the mapping. 


AIIC 


introduces named connections (arcs of a graph) between 
prcxy^ssors (using the transputer links). These connections 
need not be declared as arcs unless channels are required to 
be explicitly placed on particular links. 


EDGE 


Introduces external connections of the hardware description. 
External edges may be the host, or any peripheral connected 
via a link adaptor e.g. a joystick, disc drive. 


NETWOKK 


Defines the connections and attribute settings of previously 
declared nodes (physical processors). 


H21PPXNG 


Defines mappings between logk^al processors and physical 
processors. 


COKFIG 


Introduces the software description. 



Table 6.1 Configuration description declarations 

An'ays of nodes, edges, and arcs may be declared. A configuration description 
includes one NETWORK, one COKFIG and, optionally, one mapping. Each of the 
items appearing before COnfig behaves as an Occam specification, and ordinary 
VAL abbreviations may be included amongst these components to facilitate the 
description of scalable configurations. AHETtfORK, CONfig, orMAPPING is option- 
ally named by an identifier following its opening keyword. 

Configuration declarations are usually followed by statements which perform 
various actions relating to the declaration. Actions are defined by SET, CONNECT 
and MAP statements. The DO construct enables these statements to be grouped 
or replicated. PROCESSOR statements introduce processes which may be mapped 
onto named processors, if may be used as in Occam. Configuration language 
statements are listed in Table 6.2. 

The MAP statement may be replicated, via the DO constnjct, within a mapping 
declaration. SET and CONNECT statements may be used within a network decla- 
ration and may be combined in any order using the do statement. 



72TDS366 01 



March 1993 



JO ^ 6,2 Configuration model 



Statement 


Description 


SET 


Defines values for NODE attributes. 


CONNECT 


Defines a connection between two edges, e/ther of two 
nodes or between a node and a declared extemal edge. 


MAP 


Defines the mapping of a logical processor onto a 
physical processor declared as a NODE. Optionally 
defines the mapping of up to two channels onto an arc. 


PROCESSOR 


Introduces a software process and associates it with a 
logical or physical processor 


DO 


Groups one or more actions defined by set, connect, 
or MAP statements. 


IF 


Conditional. 



Table 6.2 Configuration description statements 

Importing code and source flies 

Gompiied code from otherffles may be referenced by means of the #USE directive, 
either at the top level, or within the CONfig construct. 

#include directives can be used to include other source files. It is suggested that 
the distinct sections are kept in different files, accessed by #INCLUDE directives 
from a 'master' file. 

The include file occonf .inc, supplied with the toolset, defines some useful 
configuration values. It can be found on the toolset libs directory. 

6.2.2 Overall structure of a configuration description 

A configuration description consists of two or three parts; a hardware network 
description, a software network description, and an optional mapping between the 

two. 

The hardware description defines processor connections. It also defines attributes 
such as processor types and memory sizes. These processors are known as 
physical processors. 

The software description is basically an Occam parallel process^ annotated with 
PROCESSOR statements to indicate which processes are to be compiled for which 
processors. These processes are allocated to logical processors. 

The mapping section can be used to ease the task of changing a particular 
program to execute on a different hardware network. The mapping section 
enables this to be performed without modifying the software description in any 
way, by flexibly mapping the logical processors onto the physical processors, see 
figure 6.1. 
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Alternative hardware descriptions 
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Figure 6.1 Configuration using logical processors 
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The following example illustrates the basic style of the language: 

— hardware description, omitting host connection 
fINCLUDE "occonf.inc" — contains useful constants 

~ for memory sizes 

NODE root.p, worker. p : — declare two processors 

ITETWORK simple , network 
DO 

SET root.p (type, laemsize := "T414", 1 * M) 
SET worker. p (type, memsize := "T800", 4 * M) 
CONNECT root.ptlink] [3] TO worker .p [link] [0] 



— mapping 

KODE root.l, worker. 1 : 

MAPPING 
DO 

MAP root.l ONTO root.p 
MAP worker. 1 ONTO worker. p 



logical processors 



— software description 

#INCLUDE "prots.inc" — declaure protocol 

#nSE "root.lku'' — must be linked units 

#USE "worker. Iku" 

CONFIG 

CHAN OF protocol root .to. worker, worker . to . root ; 
PLACED PAR 

PROCESSOR root.l 

root.proces3( worker .to* root, root. to. worker) 
PROCESSOR worker. 1 

wor ke r . process ( root . to . worker , worker . to . root ) 

This example is illustrated in Figure 6.2. 
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Figure 6.2 Mapping of software onto hardware 
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Attributes that can be set in the H2LPPING section are listed below. 



order . code 
order . vs 

order .vs 

reserved 

location . code 

location.ws 

location.vs 

routecost 

tolerance 

Xin]cquota 

nodebug 

noprofile 



Defines the priority of the program code in memory. 
Defines the priority of the program's vectorspace in 
memory. 

Defines the priority of the program's wori<space in memory. 
Defines a block of memory to be reserved for code place- 
ment. 

Defines an absolute address at which program code 
shoukj be placed. 

Defines an absolute address at which the workspace 
(stack) should be placed. 

Defines an absolute address at which the vectorspace 
should be placed (if it exists). 

Weights or de-weights specific processors in the network 
for virtual routing. 

Defines the level of usage of a particular processor for 
load-sharing routing paths. 

Defines the maximum number of links on the processor to 
be used by virtual routing. 

For use with the INQUEST debugger. Infoms the 
debugger that the process Is not to be debugged. Takes 
the values TRUE or false; the default is FALSE. 
For use with the /WQiyESTprofiling tools. Infonns the tools 
that pnscess is not to be profiled. Takes the values true or 
FALSE; the default is FALSE. 



Use of these attributes is fuliy described in sections 6.5.5 to 6.5.9. 



6,3.3 NETWORK description 

The NETWORK keyword introduces a section which describes the connectivity, and 
attributes of previously declared nodes. These should be declared outside of the 
NETWORK description, so that they are visible inside and below the NETWORK 
description. 

To describe a single processor, the SET statement provides values for the proces- 
sor's attributes in the style of a multiple assignment. 

NETWORK single 

SET processor ( type, memsize := "T800", 1024*1024) 

The type attribute must be set to a BYTE an^y (of any length) whose contents 
describe the processor type. Trailing spaces at the end of the processor's type are 
ignored. 
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Supported types are: 

'^T212" "T222" "T225" "M212" 
"T400" ""1414" "T425" 
"T800" "T801" "T805'' 

The memsize attribute must be set to the amount of usable memofy (on-chip + 
external memory) available to that processor It is expressed as a contiguous 
amount starting at the most negative address, in bytes, (k and M, defined in 
oGGonf , inc, can be used to specrfy Kbytes and Mbytes). 

Both the type and memsize attributes must be defined for all processors. No 
attribute may be defined more than once for each processor. 

The above example could also be written as a sequence of set statements in a 

DO construct: 

NETWORK single 
DO 

SET processor { type := "T800'') 
SET processor { memsize := 1024*1024) 

Since the DO constaict does not imply any particular ordering, there is no absolute 
constraint on the onjer in which attributes may be defined. However, it Is consid- 
ered good Occam style by many to declare processor types and attributes before 
other statements such as connect statements. 

If a network is to be configured to be loaded from ROM, the attribute root must 
be set to true for one processor only. By default this attribute is false for all 
processors. The attribute romsize should be set to the number of bytes of ROM 
on the root processor. These attributes are ignored if the networi< is configured to 
be booted from link. 

IF, SKIP and STOP may be used in DO constructs and are effectively executed at 
configuration time. 

Processors must be connected together by means of connect.. TO., statements 
quoting a pair of edges: 

VAL K IS 1024: 
IffiTWORK pair. from. ROM 
DO 

SET procl ( type, memsize 

SET procl ( root, romsize 

SET proc2 ( type, memsize 



= "T800", 2048 * K) 
= TRUE, 256 * K) 
= ''T414", 1024 * K) 



CONNECT procl [link] [01 TO proc2 [link] 13] 
The order of the two edges in a CONNECT statement is in'elevant 
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Arrays of processors do not need to all have the same types or attributes. They 
can be set by using DO replicators within the network constnjct, and by using 
conditionals, as in this (rather contrived) example: 

NETWORK pipe 
DO 

DO i = FOR 100 
IF 

(i \ 4) = 
SET processor[i] (type, memsize := "T800", 
4 * (1024 * 1024) ) 
TRUE 

SET processor [i] (type, memsize := "T414", 
2 * (1024 * 1024) ) 

DO i = FOR 99 
DO 

CONNECT processor I i] [link] [1] TO 

processor {i+1] [link] [0] 
IF 

(i \ 2) = 
CONNECT processorEi] Ilinic] [2] TO 
processor [i+2] [link] [3] 
TRUE 
SKIP 



More complicated expressions may also be used, as long as they can be evaluated 
at configuration time: 



VAL processors IS [''T414", "T414^S ''T414", "T800"] : 
NETWORK fancy — every fourth processor is different! 
DO i = FOR SIZE array 

SET array [i] { type :- processors [i \ 4] ) 



6,3.4 Declaring EDGEs 

Declared edges define the ends of external connections of a network. For 
Instance, a connection to another machine whose internal structure is irrelevant. 
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They are declared as though they were occam data types, and as usual we can 
declare arrays of them: 

[10] EDGE diskdrive : 
NETWORK disk. farm 
DO i = FOR 10 
DO 

— insert code to set attributes, then: 
CONNECT processor [i] [link] [0] TO diskdrive [i] 



EDGE joystick : 
NODE controller : 
NETWORK n 
DO 

SET controller (type, memsize := "T212'S 64 * 1024) 
CONNECT controller [link] [2] TO joystick 



6.3.5 Declaring ARCs 

In some circumstances a programmer may require to name a connection between 
two processors. This isn't normally necessary^ because the configurer can place 
channels between processors onto links automatically, but where a channel must 
be connected onto an external EDGE this is required. Also, if there are multiple links 
between two processors, and one link is set for some reason to go at a different 
data rate than another, the programmer might wish to have more control. 

These named links are called ARCS, and are declared as though they were Occam 
data types. They are associated with a link connection by adding a with clause 
to the end of a connect statement. 

EDGE joystick : 
ARC link. to. joystick : 
NODE controller : 
NETWORK n 
DO 

SET controller (type, memsize ;= "T212"; 64 * 1024} 
CONNECT controller [link] [2] TO joystick WITH 

link, to. joystick 
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6.3.6 Abbreviations 

Occam style abbreviations are pemritted, to enable easier reference to elements 
of arrays, etc; 



[10]NODE pipe : 
NETWORK pipeline 
DO i = FOR 10 

NODE this IS pipe[i] : 

SET this (type, memsize := "T414", 1024*1024) 



Since NODES have an attribute link, whose type is []EDGE, we can abbreviate 
one link of a processor as an EDGE: 



[lOJNODE pipe : 
NETWORK pipeline 
DO 

DO i = FOR 10 

SET pipe[i] (type, memsize := "T414", 1024*1024} 
DO i = FOR 9 

EDGE this IS pipe[i ] [link] 12] : 
EDGE that IS pipe[i+ll [link] [3] : 
CONNECT this TO that 



Simple one-to-one mappings of logical to physical processors may also be 
expressed as abbreviations: 

NODE root.l IS root.p : 

6.3.7 Host connection 

There is a predefined EDGE named HOST, which indicates the connection to a host 
computer 



NODE single : 
ARC hostlink ; 
NETWORK BOO 4 
DO 

SET single (type, memsize := "T800", 1000000) 
CONNECT single [link] [0] TO HOST WITH hostlink 



When configuring a program which is designed to be booted via a transputer link, 
one processor must be connected to the predefined EDGE HOST. 
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6.3.8 Examples of network descriptions 

1) Single processor configuration connected to host: 

flNCLUDE "occonf.inc" 

NODE MyB004: 

ARC hostlink: 

NETWORK BO 04 
DO 

SET MyB004 (type, memsize := "T414", 2 * M) 
CONNECT MyB004[lin)c] [0] TO HOST WITH hostlink: 



This configuration is 


illustrated in Figure 6.3. 
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Figure 6.3 Example of host connection 

2) Sinriple pipe witti one processor with different memory size: 

#INCLUDE "occonf,inc" 
[pJNODE Pipe: 
ARC hostLink: 

NETWORK simple. pipe 
DO 

SET Pipe[0] (type, memsize :- "T800", 2*M) 
DO i = 1 FOR p-1 

SET Pipe[i] (type, memsize '.- '^TSOD", 1*M) 
CONNECT HOST TO Pipe 10] [link] [0] WITH hostLink 
DO i = FOR p-1 

CONNECT Pipe [i] [link] [2] TO Pipe [i+1] [link] [1] 

This network is illustrated In Figure 6.4. 
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Figure 6.4 Simple pipeline with different processor memory sizes 
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3) Square array with host interface processor: 

flNCLUDE "occonf-Uic" 

VAL Up IS 0: 

VAL Left IS 1: 

VAL Down 15 2: 

VAL Right IS 3: 

H0D2 BostSquara: 

Ip] IpjNODS Square: 

ARC hostlinfc: 

NETWORK square 
DO 

SET HostSqtiare (type, mettAiz* ;= ''T414'', 2*H) 
COHKECT HOST TO HostSquare [link] [0] WITH hostlink 
CONKSCT HoBtSquareEllDk} [X] TO 

Square [p-1] [p-1] [link] [Down] 

DO i = for p 
DO j = for p 
DO 

SET Sqoare[i][j] (type, nemsize := ''T800", 1*H) 
IF 

(i = 0) AND (j = 0) 
CONNECT HoatSquare [link] [Down] TO 
SquarelO] [0] [link] [XTp] 
i = 

CONNECT Squarelp - 1] [ j - 1] [link] [Down] TO 
SquarelO ] [j ] [link] [Up] 
TRUE 

CONNECT Square[i - 1] [j] [link] [Down] TO 
Square [i ] [j] [link] [Up] 

DO i = for p 
DO j = for p 

ir 

j = (P-1) 
CONNECT Square [i] [j] Ilink] [Right] TO 

Square [{i + l)\p] [0] [link] [Left] 
TRUE 

CONNECT Square [i] [j] [link] [Right] TO 
Square [i] [j + 1] [link] [Left] 



6.4 Software description 

The software description is introduced by a CONFIG statement and may optionally 
be given a name. 

The software description itself, is an OCCam process, PAR or placed par, with 
processes annotated by PROCESSOR statements. These identify which processes 
may be placed on particular processors. The keyword PLACED is retained for 
compatibility with earlier products; it is no longer required and has no effect. 
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The NODES which are referenced by a PROCESSOR statement may be either 
physical processors if they are described as part of the hardware description, or 
logical processors if they are described as part of the software description. If the 
latter, they are mapped onto physical processors by means of a mapping section. 

Physical processor names are allowed here to simplify small networits, or those 
which will not be re-mapped, so that the programmer does not need to invent two 
names for each processor. 

The logical processor names must be introduced first by means of node declara- 
tions. These look identical to those used in the hardware description, but cannot 
have attribute settings. Since these must be visible to a following mapping 
section, they must be declared outside ihe CONFIG construct. Channels which are 
to be placed on arcs by mapping statements must also be declared outside the 
CONFIG constnjci 

A PROCESSOR statement associates the process instance (process) it labels with 
the logical or physical processor it names. The same name may be referenced in 
more than one processor statement The set of processes so named will run in 
parallel on that processor. 

The process 'inside' the processor statement may consist of Occam text. 
However, it is recommended that the code should be restricted to simple proce- 
dure calls i.e. to separately compiled procedures, referenced as linked compilation 
units using the #USE directive. Code which generates library calls is not allowed. 

Note: when imakef Is used to build the program, any linked units referenced by 
the software description must be given extensions of the type . cxx. This is 
because imakef uses a different convention for file extensions to the normal 
TCOFF file extensions, see chapter 11 in the OCCam 2 Toolset Reference Manual. 

6.4.1 Libraries of linked units 

The facility to create libraries of linked units provides an easy method of targeting 
a process at different processor types within a software description. 

For example, suppose a process is compiled and linked once for a T2 and once 
foraTS and the linked units are given imakef file extensions in order to distinguish 
them. Referencing the two linked units directly within the software description by 
#USE directives, will cause one of them to hide the other from the configurer. 

If, however, the linked units are used to create a library and this is referenced by 
a single #0SE directive, the configurer will be able to extract the correct copy of the 
process for each processor statement it finds. 

Only libraries containing linked units may be referenced from within a software 
description. 

6.4.2 Example 

The following example of a software description, is for the pipeline sorter program 
introduced in section 5.11, The example is developed to show the com plete config- 
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uration description for the program, in section 6.6. Figure 6.5 illustrates the 
mapping of tl^e software processes onto a network of logical processors, wtiich in 
this example is achieved without an actual mapping section. This method of 
mapping is explained in section 6.5.4. 

♦include "hostio.inc" — declares SP 

flNCLITOE "sorthdr.inc" — declares LETTERS 

#USE "inout.lku" — linked unit 

#OSE "element. lieu" — linked unit 

NODE inout,p ; — logical processor 

[string. length] NODE pipe. element. p : — logical 

— processors 
CONFIG 

CHAN OF SP app.in, app.out: 

PLACE ai^.inr app.out ON hostlink: 

[string. length+1] CHAN OF LETTERS pipe: 

PAR 

PROCESSOR inout.p 

incut (app.in, app,out, pipe [string. length] , 
pipe [01) 
PAR i = FOR string. length 
PROCESSOR pipe.element.p[i] 

sort . element (pipe[i], pipe[i-fl]) 



This example names a single processes inout.p and an array of processes 
pipe. element. p. The code may be mapped onto any hardware configuration 
onto which matches the defined logical network and which includes an arc decla- 
ration for the host connection hostlinJc. 



H 
O 

s 

T 



inout . p 



app. in / . . \piP«[0V.„.^4. \pip«[l] 



app . out 






pipe [ ■ tring . length ] 



Figure 6.5 Pipeline sorter — mapping processes onto processors 

6.5 Mapping descriptions 

A MAPPING structure is used if the user has declared logical processors. The 
MAPPING maps logical processors used In the software description onto physical 
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processors usecf in the hardware description. It is possible to map any number of 
logical processors onto any physical processor. The mapping description may also 
place software channels on processor Units. 

The priority at which a process runs may be determined as part of the mapping, 
if that logical process does not explicitly include high priority code. This reflects the 
fact that changes in mapping may not affect the overall structure of the software, 
but can often change the decisions made about which processes should be priori- 
tized. 

IF, SKIP, and STOP may be used in a mapping stmcture. 

As would be expected from the Occam scoping rules, logical processor names 
must be declared as nodes m the software description, before the opening 
keyword mapping of the mapping description. Each name so declared must 
appear once and once only on the left hand side of a mapping item. Physical 
processors may appear on the right hand sides of multiple mapping items. 

The mapping stnjcture itself may appear either before or after the software 
description. 



6.5.1 Mapping processes 

Having declared physical processors, as part of the hardware description, and 
logical processors, as part of the software description, we can assign logical 
processors to physical processors using the map statement 

MAPPING map 

MAP logical, proc ONTO physical .proa 



We can also supply a list of logical processors to all be mapped onto the same 
physical processor: 

MAPPING map 

MAP router. proCf application. proc ONTO root .processor 



This is exactly equivalent to: 

MAPPING map 
DO 

MAP router. proG ONTO root. processor 

MAP application. proc ONTO root. processor 
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And we can use DO replicators, and IF constructs, etc: 

MAPPING map 
DO 

DO i = FOR 10 

MAP router,proc[iI ONTO router,processor[iJ 
DO i = FOR 5 

HAP Bievft.proc[i] ONTO sieva. processor 

If we require that the process's priority be determined by the mapping, we can use 
the optional pri clause. The argument to PRi can be either to indicate high 
priority, or 1 to Indicate tow priority: 

The file occonf . inc includes two named constants HIGH and LOW which can be 
used for this. 

HAPPING map 

DO i = FOR 10 

MAJP logical. proc[i] OHTO physical. proc PRI {INT {i = 0) ) 

The configuration tool will reject the mapping at high priority of a process which 
itself indudes a PRI par. 



6.5.2 Channels 

Channels are unidirectional, point-to-point connections which may be imple- 
mented in one of four ways: 

• Sc^ channel - a channel which communicates between processes 
running on the same processor. 

• Channel edge - a channel which provides communication between the 
networi( and the outside wohd. 

• Direct channel - one of up to two channels (one in each direction) placed 
on a single link between adjacent processors. 

• Virtual channel - a channel placed on on a virtual link. 

No further action Is required at configuration time to define or place the soft chan- 
nels within an application; they are fully defined by the sofhvare itseif. 

Channel edges must be placed on a hardware arc. This can be done with a PLACE 
or MAP statement: 

PLACE f» ON hostarc: 

cx: 

MAP f 3 ONTO hostarc 
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All other channels on a network may be implemented as either dimct channels or 
virtual channels. By default the configurer automatically places software channels 
on links using the placement of processes on processors and channel edges on 
hardware edges as a guide. 

The configurer can implement many channels over a single hardware link as well 
as channels between non-adjacent processors; channels implemented in this way 
are known as virtual channels. They are implemented by software virtual routing 
processes added automatically, as required, by the configurer. 

Direct channels occur when only one or two channels (one in each direction) are 
placed on a link between adjacent processors. Direct channels may be automati- 
cally allocated by the configurer or the user may spedfically place up to two chan- 
nels on a named arc. For example, a channel edge is an example of a mandatory 
direct channel. Note: when interactive debugging with idebugand virtual routing 
are both enabled (the default), any direct non-edge channel placements will be 
ignored. 

Virtual channels enable an application program to run on most network topologies 
irrespective of the number of physical links connecting processors. The configurer 
can form virtual channels that span up to 24 hops across the target nehvork. (A 
'hop' is when a processor is required for routing a channel, zero hops implies that 
no processors were required to route the channel). Should the configurer fail to 
implement a long distance connection in a very large network, it will generate an 
error message. Chapter 10 provides further information about routing channels. 

Virtual channels are unidirectional and synchronized and are implemented by 
means of virtual links. A virtual link can be thought of as a bi-directional virtual 
connection between two processors, providing a communication path sufficient for 
two channels (one in each direction) and the appropriate synchronization signals. 

Explicit placement of channels on arcs using tf/recf channels is only required when 
connecting channels to hardware edges or where links are used for special 
purposes. For example, connection to a device, or where an application uses input 
and output channels separately, as in software implementations of high-speed 
links. In certain performance critical applications it may also be Important to avoid 
the overhead incurred when using virtual channels. 

A link may carry one explicitly placed channel as well as many virtual channels (in 
the opposite direction). In addition a pair of virtual channels (one in each direction) 
may be routed by the configurer via different physical links. 

In general channels should not be explicitly placed on arcs, unless they are edge 
connections. This enables the configurer to implement channels where applicable 
using routing and multiplexing software. 
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Attention: If it is essential that the configuration does not use any virtual routing, 
e.g. for performance reasons, the occonf 'NV' command line option should be 
used. This disables the configurer from using the virtuaf routing processes. (The 
configurer will fail if configuration is not possible, in which case the configuration 
should be modified to ensure that all channels can be placed). The bootable file 
generated ^A^II be smaller when the virtuaf routing processes are not included. 



6.5.3 Mapping channels 

Channels between processors need not be placed by the user The configurer will 
detemiine that a connection exists, and will allocate all the channels to links if they 
are available. The example in section 6.4.2 demonstrates this method and this is 
the simplest way of implementing virtual channels. If virtual channels are to be 
used it is essential that some channels are left unplaced. 

However, if a user wants to ovenide the default allocation, channels may be explic- 
itly mapped onto named ARCS. Also, channels connecting pn^cessors to external 
SDGEs must be mapped onto an ARC which connects to that edge. 

Channels are mapped onto ARCS in exactly the same way as logical processors 
are mapped onto physical processors. Two channels may be mapped onto the 
same ARC. Obviously the ARC must connect EDGES of the processors onto which 
are mapped the processes which use the channel. 

The channel behavior of the D7205/D5205/D6205 occam 2 toolsets may be 
recreated by specifying the configurer "NV* optbn, which disables ail virtual routing. 

Channels may be assigned to arcs within the MAPPING section. For example: 

EDGE peripheral : 
ARC peripheral . arc : 

NODE root.proc : — physical processor 

NETNORK n 
DO 

— inaert code to set Attribute!, then: 

CONNECT root.proc [link] [0] 10 peripheral WITH peripheral . arc 

CHAN OF protocol to,periph, from.periph : 

NODE process : — logical processor 

CONFIG 

PLACED PAR 

PROCESSOR process 

— reads frcm channel from.periph, writes to 

— channel to.periph 



HAPPING 
DO 

HAP process ONTO root.proc 

HAP to.periph, from.periph ONTO peripheral . arc 
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From the above example it can be seen tliat more tlian one channel can be 
mapped to a single arc. This mal<es it easy to place two opposing channels onto 
a transputer link using a single line of code. 



6.5.4 Mapping without a MAPPING section 

Channels can also be assigned to arcs outside the M&PPING section, using the 
PLACE statement. This is known as channel allocation. Any channel in scope at 
the point where a process is labelled is available for explicit placement on an arc 
declared in the hardware network. 

Placements must immediatefy follow the channel declaration. For example; 

CHAN OF protocol to.pdriph, from.periph : 

PLACE to.periph/ from.periph ON peripheral . arc : 

CONFIG 

PLACED PAH 

PROCESSOR root.proe 
— as before 



As with channel mapping, two opposing channels can be assigned to the same link 
in a single statement. 



6.5.5 Moving code and data areas 

Three processor attributes may be used to provide greater control of the layout of 
code and data areas in memory. Since these attributes are essentially properties 
of the user's program, not of the hardware descnption, the settings must be made 
as part ofthe MAPPING section. However, the processor which is referenced must 
be a physical processor. 

Normally the configurer arranges for the program's workspace to be given the 
highest priority, and hence placed at the lowest address on chip. This means that 
the workspace can make best use ofthe transputer's on-chip RAIVI. Program code 
is treated with next priority, and vectorspace has the lowest priority. 

These priorities can be ovenidden by setting three processor attributes: 
order. code; order. ws; and order. vs; which correspond to the program 
code, the program's workspace, and the program's vectorepace respectively. 
They are all set to by default. 

These attributes can be set to INT values, where lower integers indicate a higher 
priority. Hence setting order . code to -1 means that the program's code will be 
placed at a lower address than the workspace or vectorspace. The default 
ordering if priorities are equal is: wori^space; code; vectorspace (workspace is 
placed lowest in memory). 
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Thus we may have a mapping section like: 



MAPPING prioritise . code 
DO 

SET physical. proceasor (ordec.code := -1) 
MAP logical. processor OHTO physical, processor 

This would place the program code before the worlcspace i.e. closer to on-chip 
RAM. In this mapping vectorspace has no priority defined and is therefore placed 
by default after the workspace. 

All three attributes must be enabled on the configurer command line by the code 
re-ordering option *re'. If this option is not specified on the command line the attrib- 
utes will be ignored. 

Note: Changing the default ordering means that the INMOS debugger cannol be 
used. It is for this reason that the attributes must be explicitly enabled. 

6.5.6 Reserving memory 

A block of memory may be reserved using the processor attribute reserved. The 
block is specified as a number of bytes starting at the bottom of memory. Since this 
attribute is essentially a property of the user's program, not of the hardware 
description, the setting must be made as part of the mapping section. However, 
the processor which is referenced must be a physical processor. 

By default, the configurer uses memory in a contiguous block from the bottom of 
the transputer's available memory (near MemStart] to the top of the memory 
specified by thememsize attribute. 

This can be overridden by means of the reserved attribute. This attribute speci- 
fies the number of bytes of memory which should be reserved so that the confi- 
gurer does not use it. By default, this value is approximately the number of bytes 
below MemStart. It must be set to a positive value. 

For example: 



HAPPING reserve. low. memory 
DO 

HAP logical ONTO physical 

SET physical {reserved := #1000} 



This would ensure that the bottom 4096 bytes of memory are reserved and will not 
automatically be used by the configurer. 

Use of the reserved attribute is described in more detail in section 10,1 . 
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6.5.7 Absolute address code placement 

The location, processor attributes allow various parts of a program to be placed 
at absolute addresses in the transputer's address space. Since these attributes 
are essentially properties of the user's program, not of the hardware description, 
the settings must be made as part of the M2UPPING section . However, the processor 
which is referenced must be a physical processor. 

The address referenced by location must not have been used by the configur- 
er's normal scheme; i.e. it must either lie in an area reserved by the reserved 
attribute, or must be above memsize bytes from the bottom of memory. 

There are three location attributes: 

location . code Specifies the absolute address at which program code for 
this processor should be placed. 

location. ws specifies the absolute address at which the workspace 

(stack) for this processor should be placed. 

location. vs specifies the absolute address at which the vectorspace 

for this processor should be placed (if it exists). 

For example: 



HIIPFING use. absolute. addresses 
DO 

MAP logical ONTO physical 

SET physical (reserved := #1000) 

SET physical (location. ws :== #80000100) 



This would ensure that the bottom 4096 bytes of memory are reserved and will not 
automatically be used by the configurer, except that the woii^space is placed at 
address #800000100. (This is just above MemStart, in the transputer's on-chip 
RAM). 

MAPPING use. absolute. addresses 
DO 

MAP logical ONTO physical 

SET physical {location. code := #80001000) 

SET physical (location. vs := #80002000) 



This would place the code at address #800001000, and the vectorspace at 
#80002000- 

location attributes must be enabled on the configurer command line using 
the'RE' option. If this option is not given these attributes ^11 be ignored. 
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Use of the location attributes is described in more detail in section 10.1. 

6.5.8 Control of routing and virtual channel placement 

Three processor attributes can be used to control the way that virtual routing is 
perfonned. They are routecost, tolerance, and linkquota. Since these 
attributes are essentially properties of the user's program, not of the hardware 
description, the settings must be made as part of the mapping section. However, 
the processor which is referenced must be a physical processor. 

The exact behavior of these attributes is and their use in defining routing strategy 
for a nehvork is described in section 10.2.4. 

Values of ail three attributes are defined as numerical values. For example: 

HAPPING routing . example 
DO 

MAP logical ONTO physical 
SET physical (routecost := 1000) 
SET physical (tolerance ;= 1000) 
SET physical (linkiquot:a := 2) 



routecost: 

This attribute is used to weight and de-weight specific processors in the network 
for virtual routing- It defines an associated cost of routing virtual channels through 
a particular processor, routecost can be used to specifically exclude certain 
processors from the virtual routing networi^. 

routecost may be set to an INT value within the range 1 to 1000000 inclusive. 
If a value greater than 1000000 is specified, then no through-routing wid be 
permitted on that processor If routecost is not specified for a particular 
processor, then a default cost value of 1000 is assumed. 

MIN . COST, MAX . COST, INFINITE . COST and DEFAULT . COST are defined in the 
include file occonf . inc, see below. 

tolerance: 

This attribute is used to Indicate how much a particular processor can be used to 
provide load-sharing routing paths for other processors. 

tolerance may be set to an INT value within the range to 1000000 inclusive. 
If tolerance is not specified for a particular processor, then the default value of 
1 will be assumed. This allows the processor to implement alternative routes for 
through-routed channels with exactly the same cost as the "best" route found 
between any two other processors. 

If the value is specified, then the processor will only be used for through-routing 
if it lies on the "best" route found to implement virtual channels. 
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If tolerance is set to the maximum value 1000000 on all processors in the target 
network almost every possible route wll be used to share the cost of carrying data 
between any pair of non-adjacent processors. 

ZERO . TOLERANCE, MAX . TOLERANCE , and DEFAXJLT . TOLERANCE are defined in 
the include file occonf . inc, see below. 

linkquota: 

This attribute is used to indicate the maximum number of links on the processor 
that should be used by the virtual channel routing system. 

linkquota may be set to an INT value within the range to 4 inclusive. A warning 
is generated if the suggested linkquota for a processor is exceeded. This will 
only happen if it is necessary for through-routing other processors. 

occonf . inc 

This file contains a number of constants associated with the routing and placement 
attributes- The file must be included within the configuration description if any of 
the configuration constants are used e.g. 

#INCLUDE occonf .inc 

6.5.9 Control of debugging by the INQUESTioo\s 

Two attributes are included for use only with the INMOS INQUEST produd, 
namely, nodebug and noprof lie. These are boolean parameters which control 
the /WQaEST" debugging and profiling tools respectively They can be set to TRUE 
or FALSE. If set equal to TRUE for a process, that process will be ignored. The 
default for both attributes is FALSE. 

nodebug and noprofile have no effect on the functioning of the toolset 
debugger idebug^ or on any other tool supplied with the curent toolset. 

6.5.10 Mapping examples 

^) pipeline sorter on a single processor 

MAPPING 
DO 

MAP inout.p ONTO MyB004 
DO i = FOR string. length 

MAP pipe.element.p[i] ONTO MyB004 



2) pipeline sorter on a ring of processorSj one per process 

MAPPING 
DO 

MAP inout.p ONTO MyB004 
DO i = FOR string. length 

MAP pipe. element. p[i] ONTO ring[il 
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6.6 Example: A pipeline sorter on four transputers 

This section describes how the pipeline sorter program first described in 
section 5.11 may be distributed over four T425 transputers. Each processor has 
many processes allocated to it. 

An explanation of the configuration description is given, followed by detailed 
instrudions about how to compile, configure and run the program. 

The Occam source and configuration description developed in this example is 
supplied with the toolset in the exaa^les/manuals/sorter directory; you can 
either work in this directory or copy the relevant files to a working directory: 

sorthdr .inc the common protocol definition, 

element . occ the sorting element, 

inout . occ the interface to the host fiie server, 

sortconf .pgm the configuration description for the network. 

sorthdr . inc, element . occ, and inout . occ are the same as those used in 
the single transputer example described in section 5.11 . 

sortconf .pgm describes the hardware and software networks and maps the 
software to the hardware. The soflware description is imported in the Include file 
sortsoft.inc. 

In the configuration description it is assumed that there is a transputer network of 
fourT425 transputers connected in the pipeline configuration shown in Figure 6.6. 
If this configuration does not match your hardware the description can easily be 
modified by changing the number and type of transputers. The example assumes 
the link connections shown in Figure 6.6. 
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Figure 6,6 Pipeline of four transputers 

The mapping places an equal number of element processes on all processors in 
the pipeline after the first one, which gets any remaining element processes. 
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— To run this program connact any numbsr of id«iitical 

— transputfirs in a pipalin*; connect link 1 of proc*aEor 

— t.o lln]c 2 of proc«asoz: 1 and ao on; cooplat* tha pipalina 

--by connactifig first and laat via thair link 3i; 

— finally connect procasaor to the host. 

— max no of cltaxs on a lizi* 

VAL string. langth IS SO; 

— include useful definitions e.g. l^Kllo, H=Haga 

SIHCLUDE "oeconf ^inc" 

— change t2i« following to suit your natirork 

VAL nlmibar-of ,traji3put4rs IS 4: 
— declare procassozs as an array 
[nizDbar.of .tranaputars]HODE pipalizia.t: 
ARC Hostlink; 

— hardware description 
NETWORK 
DO 

CO i K Q ion number. of .transputara 

'-- change the following to suit your transputer type 
SET pipeline. t[i] (type^ memslE* :* "Ti2B" , 1*HJ 

DO 1 - FOR nunber.of. transputers - 1 

CONNECT pipeline. t[i] [link] [21 TO pipeline. t[i+l] [link] [1] 

CONNECT pipellne.t[nui[]ber.Df. transputers-!] [Ilnkn31 TO 
pipeline. t[a I [link] [3] 

CONNECT pipeline. tlO J [link] [IJ TO BOST WITH Hoatlink 



— mapping 

VAIi nuodsar . of . elements IS string. length: 
— numt>er,of.element9/numb«r. of .transputers must be >- 2 
VM. eLemanta.par.tranapxitaT IS number, of .elements/number , of . transputers: 
VM. remaining- elements IS niimber.af.elements\nuinber.cf. transputers: 
VAIi elements .on. root IS elements. per. transputer + remaining. elements : 
NODE inout.p: 
[nuinbecof .elements]IitODE pipe,*leaent,p: 

HAFFIHG 
DO 

MAP inout.p ONTO pipeline. t[0] PRI HIGH 

DO i ■ FOR elements. on. root-1 

HAP pipe. element. p[i] ONTO pipeline. t[0] PRi IX>tr 

tRP pipe. element. p[ elements. on. x-oot-1] ONTO pipeline. t[0] PRI HIGH 

DO ^ 3E FOR number. of .transputers - 1 

VAL first. element. heE« IS elements. on. root + (j*element9,per, transputer ] : 
VAL last. element. here IS first. element. here 4- (elements .per. transputer-1} : 
DO 

HAP pipe. element. p[first. element. here] ONTO pipeline. 1 1 j+1] PRI HIGH 
DO i V first. element. here 4- 1 FOR elements. per. transputer - 2 
HAP pipe. element. p[i] ONTO pipeline. t[j+l] PRI LOH 
HAP pipe. element. p[last. element. here] ONTO pipeline. tIj+1] PRI HIGH 

-"Software description 
flNCLUDE "hostio.inc" 
fINCLDDE "aorthdr.inc" 
#USE *inout.lku" 
#USE "element. Iku'' 
llNCLUDE "soitsoft.inC 
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In the mapping stmcture shown, the logical processors named in the software 
description are mapped onto the physical processors declared in the hardware 
description. Note: On each processor, processes which communicate on external 
channels are mapped to be run at high priority. 

The allocation of processes to transputers is shown in Figure 6.7. The number of 
elements on each processor depends on the maximum string length permitted by 
the program and the number of transputers in the pipeline. 



transputerO 




transputer 2 



Figure 6.7 Pipeline sorter pnDcesses 

6,6,1 Building ttie program 

The components of the program must be compiled in a bottom up fashion. First 
compile the sorting element: 



oc element -t425 
oc element /t425 



(UNIX) 
(MS-DOSA/MS) 



Because the file has a , occ file extension you can omit the extension from the file- 
name. The command line option to specify the error mode may be omitted 
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because the default is required i.e. HALT mode, but the T425 transputer target 
must be specified. The compiler creates a file called element, tco. 

Next compile the input/output process: 

oc inout -t425 (UNIX) 

oc inout /t425 (MS-DOS/VMS) 

This creates the file inout. tco. 

These files must now be linked. Because the two processes are to be placed on 
separate processors, each must be linked individually, together with any files they 
reference. Each linking operation creates a unit of code which may be loaded onto 
the transputer network, according to the configuration defined in the configuration 
description. 

To link element . tco: 

ilinfc element . tco -f occama.lnk -t425 (UNIX) 

ilinfc element. tco /f occama.lnk /t425 (MS-DOSA/MS) 

This creates a file called element, lieu. The linker indirect file occama.lnk 
contains the necessary references to the compiler libraries. (This file is supplied 
with the toolset.) 

To link inout. tco: 

ilink inout -tco hostio.lib -f occama.lnk "t425 
(UNIX) 

ilink inout. tco hostio.lib /f occama.lnk /t425 
(MS-DOSA/MS) 

This creates a file called inout . ifcu. 

Now configure the file sortconf.pgm which defines both the communication 
channels between the processes and how they should be loaded onto the network: 

occonf sortconf 

This creates an output file called sortconf , cfb. The Input file extension can be 
omitted as occonf assumes .pgm. 

Finally the program must be made executable. To do this run the collector tool 
icollectonthe .cfb file. 

ieollect sortconf .cfb 

This creates the bootable file sortconf .btl is created. The file extension is 
required. 
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6.6.2 Running the program 

Load and run the bootable file on the transputer network using iserver: 
iserver -se -sb sortconf .btl (UNIX) 

iserver /se /sb sortconf .btl (MS-DOSA/MS) 

The 'se' option directs the server to terminate if the program sets the en^orflag. 

If the pipeline networic is connected to the host via a root transputer use the skip 
loadertojumpoverthe root transputer, and use the iserver 'ss' and 'sc' options 
rather than 'sb'. In the following example the pipeline networ1< is connected to link 
2 of the root transputer 

iskip 2 -e -r 

iserver -se -ss ^sc sortconf. btl (UNIX) 

iskip 2 /e /r 

iserver /se /ss /sc sortconf. btl (MS-DOSA/MS) 

In either case the program sorts each line of Input until terminated by a blank line. 

6.6.3 Automated program building 

As with the single processor version of this program it is possible to automate the 
building of this program with the Makefile generator tool and a suitable MAKE 
program. The version of the configuration program supplied in the fiJe sort- 
mat . pgm is written using imaJtef file naming conventions, for example, the linked 
units are given file extensions of the form cxx. 

Kote: sortmak . pgm compiles the program for transputer class TA in HALT error 
mode - it references the linked units as . cah files and is configured for T425 trans- 
puters. For a list of transputer targets see appendix B in the Occam 2 Too}set 
Reference Manual. 

To produce a Makefile for the program type: 

imalcef sortmak.btl 

This will produce a file called sortmak .mak containing a MAKE description for the 
program. It will also produce linker Indirect files for the two compiled units which 
comprise the program; these will refer to any necessary modules from the library. 

To build the program run your MAKE program on the file sortmak . raak and a[l the 
necessary compiling, linking and configuration will be done automatically. For 
more information about MAKE programs see Chapter 11 In the Occam 2 Toolset 
Reference Manual 

6.6.4 Other configuration examples 

Example .pgm files which configure the sorter program for other networks are 
supplied on the sorter directory. Descriptions can be found in the source files and 
in the readme file for the directory. 
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6.7 Conditional configurations 

Conditional constructs (IF) are permitted inside network, mapping and CONFIG 
constructs. This makes it possible to create configuration descriptions which can 
be 'conditjonaify complied' for different network structures. 

For example, while developing a program, it may be useful to modify a program 
to bypass the root processor, so that an application may be placed directly onto 
an application processor. The following, rather trivial, example demonstrates this. 

6.7.1 Example: Configuration using conditional IF 

In this example, when a single processor is in use, the application communicates 
directly with the host, as shown in Figure 6.8. When two processors are available, 
a buffer process is loaded onto the root processor This process buffers the 
communication between the application and the host. See Figure 6.9. 
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Figure 6.8 Direct host connection 
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Figure 6.9 Communication via the root processor 

The implementation is split into the following files: 

app . occ - the application 

buff . occ - the buffer process 

myprog.pgm - the configuration description file 

The content of app . occ Is as follows: 

#IHCLUDE "hostio.inc" 
fUSE "hostio.Iib" 

PROC application. process (CHAN OF SP fs, ts) 
SEQ 

so. write. string. nICfs, ts, "Hello world''] 
so . exit (£s , ts , sps . success) 
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The content of buff . occ is as foHows: 

flKCLUDE "hostio.inc" 
#USE "hoatio.lib" 

PROC buffer, process {CHAN OF SP fs^ ts, frcaa.Qpp, to.^pp) 
CHAN OF BOOL stopper : 
— This never terminatAS 
so. buffer (fs, ts, from.app, to.app, stopper) 

The content of myprog . pgm is as follows: 

VAL nuaiber. Of .processors IS 1 : — 1 when nanning, 

— 2 for developing 
HODE root^ application : 
ARC hostlink, rootlink : 

NETWORK 
DO 

IF 

nusdber. of .processors = 2 
DO 

SET root (type, memsize := "Ti25", #100000) 
CONNECT root [link] [0] TO HOST WITH hostlink 
CONNECT root [link] [31 TO application [link] [0] WITH rootlink 
TRUE 

COWSECT application [linkj [0] TO HOST WITH rootlinJc 
SET amplication (type, raonsize := ''T414'\ #100000} 

#INCLDDE ''hostio.inc" 
#USE "app.eah" 
#US£ "buff.cah" 
CONFIG 

CHAN OF SP fs, ts : 

^LA£E fs, ts OH rootlink : — Note that this is ^rootlink' , not 

— ^hosUink' 
PAR 
IF 

number, of .processors ~ 2 
CHAN OF SP fsO, tsO : 
PLACE faO, taO ON hostlink : 
PROCESSOR root 

buffer .process (fsO, tsO , ts, fs) 
TRUE 
SKIP 
PROCESSOR application 

application. process (fs, ts) 

The configuration uses a constant to set the number of available processors. This 
is then used to conditionally build the program for one or two transputers, nodes 
which are declared, but do not have any attributes set, are ignored when confi- 
guring a program. 

The program can be built manually or using imafcef . Note: when building the 
program for two processors, warning messages will be generated concerning 
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interactive debugging; these can safely be ignored. Disabling interactive debug- 
ging with the imakef 'y' option will prevent the warnings being generated. 

Source files can be found on the examples/manuals/conf ig directory. When 
building manually remember to use imakdf naming conventions - the program 
is configured for a T414 transputer and HALT en^or mode. The output of the 
program is 'Hello World'. 

6.8 Summary of configuration steps 

To summarize, the steps involved in building a program that runs on a network of 
transputers are as follows: 

1 Decide how your program will be distributed over the transputers in your 
network. 

2 Write a configuration description for your program by: 

3 Describing your hardware network, 

4 Inserting PROCESSOR statements into your program and adding any 
necessary mapping description. 

5 Compile all the separate compilation pnx»dures that form the code for 
each transputer in a bottom up fashion. 

6 Link each configuration procedure with its component parts into a file with 
the name used in #U5£ directives in the configuration source file. 

7 Run the configurer on the configuration description file. 

8 Collect the code using icollect. 

9 Load the program into the network using the host fife server 

Steps 5 to 8 can be automated by using imakef and a suitable MAKE program. 

6.9 Further considerations 

6.9.1 The effect of occonf on idebug 

The use of command line options to occonf has a direct effect on the way in which 
the interactive/post mortem debugger idebug can be used to debug the program. 

There are two main ways of using occonf: 

• No special command line options, {the default) - this is compatible with 
either the interactive or postmortem debugger. However, the real time 
performance of the bootable produced may be significantly different to that 
produced by using the Y option, if there is a high incidence of channel 
communication between processors. 
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• With the Y command line option - this is compatible with the postmortem 
debugger only. 

Important note: when virtual routing processes are used, idebug cannot jump 
down channels between adjacent processors. If this is required, the configurer 'NV' 
option should be used to disable virtual routing. 

Table 6.3 summarizes the use of the relevant options. 



occonf command options 


Effect 


'NV' 


Interactive and post-mortem debugging enabled. 

Virtual routing disabled. 

Possible to jump down channels between adja- 
cent processors. 


default settings 


Interactive and post-mortem debugging enabled. 

Virtual routing enabled and will be used even if not 
required, Le. direct channel placements between 
processors will be ignored. 

Not possible to jump down channels between 
adjacent pnacessors. 


^^and IIV 


Post-mortem debugging enabled. 

Virtual routing disabled. 

Possible to jump down channels between adja- 
cent processors. 


'Y' 


Post-mortem debugging enabled. 

Virtual routing enabled and may be used. 

Only possible to jump down channels between 
adjacent processors if they are not used for virtual 
routing. 



Table 6.3 Effect of occonf options on debugging 

6.9.2 Reliable Channel Communications 

There are a number of library routines that can be used to handle faults in the 
communication network. These can be used only on direct channels (see section 
6.5.2). They must not be used on virtual channels, nor during debugging. The 
routines are: 



PROC InputOrFail, t 



(CHAK OF ANY c, []BYTE mess, 
TIMER t, VAL INT time, 
BOOL aborted) 



PROC OutputOrFail . t (CHAN OF ANY c, 

VAL I] BYTE mess, 
TIMER t, VAL INT time, 
BOOL aborted} 
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PROC InputOrFaiX.c (CHAN OF ANY c, []BYTE mess, 
CHAN OF INT kill, 
BOOL aborted} 

PROC OutputOrFail.c (CHAN OF ANY c, 

VAL []BYT£ mess, 
CHAN OF INT kill, 
BOOL aborted) 

The routines attempt a transfer of data on a channel. Those ending in . t include 
a timeout for failed cx)mmunication, those ending in .c send a status message on 
another channel. If the communication succeeded nonnally, aborted is set to 
FALSE; if the communication was aborted (on timeout or linkfailure, depending on 
which routine was used), aborted is set to TRDE. 

Note: These routines are not intended as the nornial mode of communications. 
They have a higher overtiead than other methods. 

A further routine is available to reset a channel that has gone awry in its commu- 
nications. This is: 

PROC Reinitialise (CHAN OF ANY c) 

For example, when a hard link is quiescent it can be reset by this routine. 

Full descriptions of all these routines can be found in section 1.10 of the Occam 
2 Toolset Language and Libraries Reference Manual. 

Important note: These routines should not be used for checking the communica- 
tions within a network if there Is any doubt as to whether the data might not have 
transfen-ed in a given amount of time. In general, you should be absolutely sure 
that the failure is due to a hardware failure, and not to the receiving or sending 
device being very busy. If the communication is terminated while data is actually 
being transmitted, then the results are undefined, and could stop one or both of 
the processors. 

There is no point in using these routines on soft channels, because the commu- 
nication on soft channels can be assumed to be secure. 



6.9,3 Checking the configuration 

Configurations may be checked against the hardware on a transputer board using 
a network check program such as ispy. The ispy program is supplied as part of 
the support software for some INMOS /q systems products. 

INIVIOS iq systems products are available separately through your local INMOS/ 
SGS'THOIVISON authorized distributor or SGS-THOMSON sales office. 
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This chapter explains how to load programs onto single transputers and transputer 
networks. It briefly describes the format of loadable pre)grams and introduces the 
program loading tools iaerver and iskip. The chapter goes on to explain how 
to load programs for debugging and ends with an example of skip loading. 

7-1 Introduction 

Transputer programs are loaded onto transputer boards with the iserver tool 
which installs code on each processor using processor and distribution information 
embedded in the executable file. The executable file consists of code to which 
bootstrap information has been added to make the program self-booting on the 
transputer. Self-booting executable code is also imown as bootable code. 

Bootable files are generated by icollect from configuration data files {networi< 
programs) or linked units (single transputer programs). Bootable files are gener- 
ated with the default extension .bti {for loading onto boot from link boards), or 
-btr (for loading onto boot-from-ROM boards). Note: a bootable fife is 
constructed such that copying it to a link will boot the network automatically. 

7.2 Tools for loading 

Two tools are pnDvided to load programs onto transputers and transputer netWDri<s: 

• iserver — the file server and loader tod. 

iserver loads the bootable file onto the single transputer or transputer 
networicand activates the host file server that provides communication with 
the host. 

• iskip — the skip loading tool. 

iskip allows a program to be loaded over the root transputer onto an 
external network. The tool is used prior to invoking iserver to start up 
a special route-through process on the root transputer that transfers data 
between the the network and the host system. 

Skip loading is useful for the post-mortem debugging of programs that do not use 
the root transputer. The root transputer in the network is omitted from the logical 
network and the program is loaded onto the first processor afferihe root transputer, 
leaving it free to run the debugger This avoids having to debug the code from a 
memory dump file. 
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Programs loaded using isfcip always require one extra processor on the network 
in addition to those required to run the program. For example, a program written 
for a single transputer requires at least two processors, one to act as the root trans- 
puter and one to run the program. 



7.3 The boot from link loading mechanism 

iserver loads programs onto transputer networks, via the host link connection, 
it does this by simply copying the contents of the bootable file to the link. The boot- 
abfe file contains all the bootstrap and loader code to ensure that the program is 
loaded onto the network and starts running. 

The server has to be told which link connection to use and how to access it. This 
is done by specifying the name of a User Link on the command line or in the envi- 
ronment variable transputer. The server gets information about the specified 
User Link from a connection database file. See the iserver documentation in 
chapter 13 of the Toolset Reference Manual 

The bootstrap code for the transputers in the network is sentfirsL The code is prop- 
agated through the network as individual processors load neighboring processors. 
After all of the transputers in the network have been booted, program code Is 
loaded onto individual processors. For a multitransputer network the allocation of 
processes to processors is determined by the configuration file. For single trans- 
puter programs code is loaded onto the first processor on the network. 

When all of the code is loaded into the transputer's memory, the program starts 
running and can communicate with the host using the standard library routines for 
input and output. The libraries actually communicate with the host via the server 
using a predefined communication protocol known as the 'SP' protocol. This 
protocol is defined in the iserver documentation. 

The program continues to run until: an error occurs, the server is terminated by 
pressing the iserver inten-upt key (usually CTRL-C or CTRL-BREAK), or the 
program terminates naturally. Note: terminating the server will not stop the 
program running on the transputer However, any processes on the transputer 
which attempt to communicate with the server will deadlock. This may eventually 
cause the whole program to stop as other processes become dependent on this 
communication. The program may be able to continue if the server is restarted. 

If iskip is used, the first transputer in the network is bypassed. Therefore the 
network must contain one additional transputer to the number required to run the 
program. 



7.4 Boards and subnetworks 

There are two basic types of transputer evaluation board: those that boot from link 
and those that boot from ROM. 
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Boot from link TRAM boards form the majority of transputer boards in general use. 
They are loaded down the link that connects the root transputer to the host using 
the iserver tooL Programs intended to run on boot from link boards must consist 
of bootable code, such as that generated by icollect. 

Examples of boot from link boards supplied by INMOS are the IMS BOOS PC 
motherboard (with appropriate TRAMs) and the IMS B014and IMS B01 6 VME bus 
standard inteiface boards. 

Boof from ROM TRAM boards are intended for stand-alone applications such as 
embedded systems. 

7.4.1 Subsystem wiring 

Subsystem wiring is the way in which boards are connected together, and deter- 
mines the manner in which transputer subnetwori^s are controlled. 

Three signals are used to control transputers mounted in a system, namely Reset, 
Analyse, and Error Together these are known as the system serv/ces. All INMOS 
transputer boards use a common scheme for propagating these signals to other 
subnehtforks. The scheme is as follows. 

Each b^nsputer board has three ports for communicating system services from 
one board to another. These are Up, Down, and Subsystem. Up is the input port, 
used to control the board from an external source; Down and Subsystem are both 
output ports and are used to propagate the Up signals to other boards or subnet- 
works. 

The Down and Subsystem ports work in the following ways: 

Down propagates the Up signal unchanged to the next board or subnetworit. This 
allows multiple boards to be chained together by connecting successive Up and 
Down ports and the whole networic can be controNed by a single signal. 

Subsystem propagates the Reset and Analyse signals but also allows control by 
the board, enabling subnetworks downstream of the board to be independently 
reset, analyzed, and their enror flags read, under the control of the transputer to 
which the subsystem is attached. 

7.4.2 Connecting subnetworks 

Multiple transputer systems can either be controlled by the host computer or by a 
masfer transputer controlled by the host computer. 

In a typical multitransputer system the root transputer's Up port is connected to the 
host computer so that the host can control the loading of programs and monitor 
errors on the network. The first processor in the subnetwori< is connected to either 
Down or Subsystem depending on the application, and other processors on the 
network are chained together via their Up and Down ports. 
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In a simple application requiring multiple transputers, the subnetwork would 
nomially be connected to Down on tiie root transputer. Tills would allow the host 
computer to reset the whole network in a single operation and to monitor the en'or 
signal on any transputer in the network. 

A more complicated application may require several programs to be (oaded onto 
the subnetwork underthe control of the root transputer Here the subnetwork would 
be connected to Subsystem so that the root transputer could repeatedly reset and 
re-load the subnetwork. Any errors in the subnetwork would be detected by the root 
transputer through its Subsystem port, and the error would not be propagated 
through the Up port to the host computer. Reset and Analyse signals are propa- 
gated through to the Subsystem port, but the error signal is not relayed back. (Note 
some boards do not confonn to this system of signal propagation, see 7.5.2). 

7.5 Loading programs for debugging 

Special debugger and server options must be used for the debugging of programs 
running on transputer boards. The options vary with the subsystem wiring, the 
board type^ and whether or not the program uses the root transputer The effects 
of subsystem wiring are described above; the effects of board type and program 
mode are described in the following sections. 

Commands to useforvariouscombmations of subsystem wiring, board type, and 
program mode, are listed in the debugger reference documentation. 

7.5.1 Breakpoint debugging 

Programs are loaded for breakpoint debugging using the idebug command. 
When invoked in interactive mode this command incorporates a skip load and 
iserver is not required. Because it uses a skip load, breakpoint debugging 
requires at least two processor on the network. 

7.5.2 Board types 

Some eariy INMOS boands of the B004 type, unlike later TRAM-based boards, do 
not propagate Reset through to the Subsystem port. On these boards the 'A' 
debugger option must be supplied on the debugger command line to reset the 
network. 



7.5.3 Use of the root transputer 

The use made of the root transputer by the program changes the methods you 
must use in post-mortem debugging. This is because the debugger program 
executes on the root transputer and any application code becomes ovenvritten 
when the tool is invoked. 

Two methods can be used to load and debug code running on the root transputer: 
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This chapter describes how programs communicate wth the host computer via the 
host file server and the i/o libraries. It briefly describes the protocols used, outlines 
how to place host channels on a transputer board, and discusses how processes 
can be multiplexed to a single host. 



8.1 Introduction 

Occam, [ike most high level programming languages, Is independent of the host 
operating system. At the programming level, communication with the host is 
achieved via a set of i/o libraries that are provided with the toolset. The libraries 
in turn use the services provided by the host file server. The host file server and 
the functions it provides are transparent to the programmer. The sender functions 
are activated whenever a program is loaded using the iserver tool. Programs 
that use the i/o libraries should always be loaded using iserver. 

For an example of a program that communicates in a simple way with the host 
computer, including details of how it is compiled, linked and loaded, see Chapter 5. 



8.2 Communicating with the host 

Programs communicate with the host through i/o library routines that in turn use 
functions provided by the host fiie server. 



8.2.1 The host file server 

The host file server prowdes the runtime environment that enables application 
programs to communicate with the host, li contains functions for: 

• Opening and dosing files 

• Reading and writing to files and the terminal 

• Deleting and renaming files 

• Returning infomiation from the host environment, such as the date and 
time of day 

• Returning information specific to the server, such as a version number 

• Starling and stopping the server 
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Details of the server functions can be found in appendix C of the OCCam 2 Toolset 
Reference Manual. 



8,2,2 Library support 

Two i/o libraries are provided for accessing the file system and other host services. 
The libraries are summarized below. 

hostio . lib File and terminal i/o; host access 

streamio , lib Stream-based temiinal and file i/o 

All routines in these libraries are independent of the host operating system. 

The hostio library contains basic routines for accessing files and controlling the file 
system. It also contains routines for general interaction with the host. Use the 
hostio library for basic file operations, and for accessing host services. 

The streamio library contains routines for creating and outputting to streams. It 
also provides primitives for reading and writing text and numbers, and for control- 
ling the screen. Use the streamio library for inputting and outputting character and 
data streams. 

Definitions of constants and protocols used within the libraries are provided in the 
include files hostio . inc and streamio , inc. These files should be included in 
all programs where the respective libraries are used. 

Details of all i/o procedures and functions can be found in the occem 2 Toolset 
Language and Libraiies Reference Manual. 



8.2.3 File streams 

The host file server supports a stream model of file and terminal access. When a 
file is opened a 32-bit integer stream id is retumed to the program. This identifier 
must be quoted by the program whenever the file is accessed, and is valid until the 
file Is dosed. Streams and files must be explicitly closed by the programs that use 
them, and the server must be explicitly terminated when the program finishes and 
host services are no longer required. 

Three streams are predefined: 

spid, stdin standard input 

spid . stdout standard output 

spid.stderr standard error 

These streams can be closed by the programmer, but cannot be reopened. Take 
care not to close the standard streams if you are using hostio routines that read 
or write to them . The streams ca n only be closed by specifying the stream id explic- 
itly and cannot be closed inadvertently using the hostio routines. 
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Standard input and output are normally connected to the keyboard and screen 
respectively, but may be redirected by the operating system. Streams and files 
other than the three standard streams described above must be explicitly dosed 
by the program. When the program finishes and host services are no longer 
required, the server should be temninated by the transputer application calling 
so. exit. 

Protocols 

Occam programs communicate with the host file server through a pair of occam 
channels. Requests for service are sent to the host on one channel and replies are 
received on the other. Both channels use the SP protocol, which is defined in the 
include file hostio . inc. 



8.3 Host implementation differences 

The IBM PC version of the host file server supports a number of DOS specific 
commands via routines in the library file msdos . lib. The VAXA/MS and UNIX 
implementations have no host specific commands. 

If you wish to write programs that are portable between all implementations of the 
toolset you are recommended to use only host independent routines. All proce- 
dures and functions in the hostio and streamio libraries are host independent. 



8-4 Accessing the host from a program 

For programs to be run on transputer boards the host Is accessed through the 
channels f s and ts, both defined as CHfiN OF SP. Protocol SP is defined in the 
include file hostio. inc. For single transputer programs the channels are 
defined within the program, and for multiprocessor programs the channels are 
placed on the link that is connected to the host. The normal location for the connec- 
tion to the host is link zero on the root processor. 



8.4.1 Using the simulator 

The simulator tool isim provides access to the host file server in the same way 
as a single processor program running on a board, connected via link 0. 



8.5 Multiplexing processes to the host 

The host file server is a single resource, connected to a process running on the 
root transputer via a pair of OCCam channels. This is illustrated in Figure 8.1 . 
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8.2 Communicating with the host 
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Figure 8.1 Program input/output 

If more than one process requires access to the host then the server must be 
shared between a number of processes, ensuring that all pnxesses are served 
in turn. The simplest solution where a resource Is used by more than one process 
is to provide a multiplexor. 

A multiplexor is a process which takes many inputs and connects them to a single 
shared resource and ensures that communications from different processes do 
not conflict. 

Four routines that allow multiple processes to communicate with the host via the 
host file server channels are provided in the hostio library. The routines are: 
so. multiplexor; so. overlapped. multiplexor; so. pri. multiplexor; 
and so, overlapped, pri -multiplexor. Details of the routines can be found 
in section 1.5.9 of the Occam 2 Toolset Language and Libraries Reference 
Manual. 

An example of a multiplexed system is shown in Figure 8.2, and the Occam code 
that would implement the system is listed in Figure 8.3. 




Figure 8.2 Multiplexing the host file server 
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#INCLUDE "hostio.inc" — SP protocol declaration 
PROC mux. example {CHAN OF SP fs, ts, 
[3 INT free. memory} 

#OSE "hostio.lib" ~ host i/o libraries 

#USE "processO" — user processes 
#USE "processl" 
#nSE "process2" 
SEQ 

CHAN OF BOOL stop: 

[SJCHAN OF SP from. process, to. process: 

PAR 

so. multiplexor (f 3, ts, — server channels 
from. process, to. process , 

— multiplexed channels 
stop) — termination channel 

SEQ 

PAR — run user processes in parallel 
— sharing the iserver 
processO (to. process [0] , f rom. process [0] ) 
processl (to . process [ 1 ] , from . process [ 1 ] ) 
proceas2 (to, process [2] , from. process [2] ) 
stop ! FALSE — terminate multiplexor 
so. exit (fs^ ts, sps, success) 



Figure 8.3 Multiplexing example 

This source for this program can be found in examples/manuals/mux. 

Multiplexor processes can be chained together to produce any degree of multi- 
plexing to the host. However, the host is a single, finite resource and unrestrained 
multiplexing of processes should be avoided if possible. 

8.5.1 BufTering processes to the host 

It may sometimes be useful to pass data invisibly through another process, for 
example when passing data to the server through inten^ening processes. The 
hostio library routine so. buffer talces a pair of input and output channels and 
passes data through unchanged. 

8.5.2 Pipelining 

If data has to pass through many processes before reaching the server efficiency 
may be Improved by allowing a data transfer to begin before the previous one has 
completed its journey down the [ine of processes. This allows several data trans- 
fers to be in progress simultaneously and is known as pipelining. 
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The routine so . overlapped, buff er can pipeline several buffers up to a user- 
defined limit. A pipelined version of the multiplexor process called so .overlap- 
ped . multiplexor perfomis the same function for multiplexed processes. Priori- 
tized versions of the routines may also be used. 
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9 Debugging 

transputer progranns 



This chapter describes how to debug transputer programs, tt describes the faciti- 
ties of the toolset debugger idebug and shows how they can be used to debug 
transputer programs in a systematic manner. It explains how the debugger can be 
used in two modes (post-mortem and interactive) to analyze transputer programs 
and describes the two debugging environments (source code symbolic and low 
level monitor page). The chapter ends with some hintsabout debugging transputer 
programs and a list of points to note when using the debugger. 

Worked examples are given at the end of this chapter, the sources of which may 
be found in the toolset examples subdirectory. 

Chapter 4 of the accompanying Toolset Reference Manual provides detailed 
information about idebug, Including command line syntax and full descriptions of 
the symbolic debugging and monitor page commands. 

9.1 Introduction 

The networi< debugger idebug is a symbolic debugger for transputers and trans- 
puter networks. It can be used to examine stopped programs (post-mortem debug- 
ging) or to debug programs interactively (breakpoint debugging). It can be used 
with INMOS ANSI C, Occam, and FORTRAN-77 programs, and with mixed 
language systems. 

Programs can be analyzed using the symbolic functions which operate using 
source code symbols or the monitor page commands which operate at memory 
and processor level. 

Symbolic functions allow files to be examined, variables inspected, and proce- 
dures traced, from source code level. Monitor page commands allow transputer 
memory to be examined and processor state to be determined anywhere on the 
network. Symbolic and monitor page environments are separate but can be 
switched between at will. 

idebug can be used to debug mixed language programs, although certain facili- 
ties are available for some languages and not others. For example, a comprehen- 
sive expression language exists for C and a simpler one for occam. The exact 
usage of some facilities may also differ slightly between languages. 

9.1.1 Post-mortem debugging 

Post-mortem mode debugging allows stopped programs to be analyzed from the 
residual contents of transputer memory or from a network dump file. Programs that 
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run on the root transputer must be debugged from a memory dump fife because 
the debugger ovenvrites the root transputer's memory. The memory dump file is 
created using the idamp tool (see chapters 4 and 5 of the accompanying Toolset 
Reference Manual). 

9.1.2 Interactive debugging 

interactive debugging (also known as breakpoint mode debugging) allows trans- 
puter programs to be executed interactively using breakpoints set in the code. 

Breakpoints can be set symbolically on lines of source text or at transputer memory 
addresses, and values can be modified in transputer memory to show the effect 
of changing variables. Breakpoint mode debugging requires the use of two or more 
transputers, because the debugger tool runs on the root transputer. 

Certain symbolic functions and monitor page commands are only available in 
breakpoint debugging mode. 

9.13 Mixed language debugging 

When debugging programs constructed from a mixture of languages from different 
INMOS toolsets, you should alwa^ use the version of idebug with the highest 
version number (as displayed in the help or monitor pages). This is true for all 
versions of idebug with a version number greater than V2 . 00. 00. This will help 
ensure that no toolset incompatibilities occur. 

9.1.4 Debugging with isia 

The transputer simulator tool isim can also be used to debug transputer 
programs from a low level environment. Using a similar environment to the 
debugger monitor page transputer memory can be examined, breakpoints set, 
and programs executed by single stepping. 

The debugging facilities of the simulator are briefly described in this chapter 
(section 9.13). Details of how to use the simulator tool can be found in chapter 14 
of the accompanying Toolset Reference Manual. 



9.2 Programs that can be debugged 

The debugger can analyze programs running on transputers that are eitherdirectly 
attached to a host through a server program, or connected to the host via a root 
transputer. 

The roof transputer is the processor that is directly connected to the host computer. 
In a transputer network that is connected to the host it forms the root of the network. 
The debugger always runs on the root transputer, which must be a 32-bit trans- 
puter with at least one megabyte of memory (preferably two or more). 
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The relationship of the root transputer to the host computer and the rest of the 
network is illustrated in figure 9.1, 
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Figure 9.1 Debugging a transputer network 

If breakpoint debugging is used the transputer network must contain at least two 
processors because the root transputer is dedicated to running the breakpoint 
debugger in parallel with the user's program. 

9.3 Compiling programs for debugging 

Programs to be debugged should be compiled with full symbolic debugging 
infonnation enabled. For C and FORTRAN, this is achieved by specifying the 
compiler 'G' option when the program is compiled. The occam compiler generates 
object files containing full debugging information by default. Two command line 
options may be used to limit the debugging information produced by the compiler. 

Minimal debugging information 

By default the C and FORTRAN compilers generate object files containing minimal 
symbolic debug information so that object modules, especially those to be used 
as libraries, are kept as small as possible. Minimal debug infomiation enables the 
debugger to backtrace out of a library function to a module compiled with full debug 
information. 

Occam programs can be compiled with minimal debug information by using the 
compiler 'D' option. 

Kote: The object code produced by the C and FORTRAN compilers with minimal 
debug information contains certain optimizations that are absent in code gener- 
ated with full debugging information enabled. As a consequence the object code 
produced may differ slightly from code compiled with full debugging information 
enabled. 

OCCain channel communication 

The 'Y' option to the occam compiler disables channel communication via library 
routines and, instead, produces optimal in-line code for channel i/o. Interactive 



72TDS366 01 



March 1993 



118 9.2 Programs that can be debugged 

debuggfng requires alf communications to be done by means of the iibrary 
routines, so this option also disables interactive debugging. 

C channel communication 

Use of the C library DirectChan functions on channels provided by the configurer 
will interfere vwth and corrupt interactive debugging. Note that the DirectChan 
functions can be safely used with edges passed from the configurer, and with 
internal (soft) channels declared in C source files. 



9.3.1 Error modes 

Programs to be debugged should be generated in HALT mode, which is the linker 
defauft. The behavior of a program when an en-or occurs depends on the mode 
in which the program was compiled and linked, as follows: 

• In HALT mode any error during program execution halts the transputer 
immediately. 

• In STOP mode, errors do not halt the program, rather they slop the errant 
process allowing other processes executing on the same transputer to 
continue. Programs compiled in this mode can only be debugged if they 
are halted explicitly. 

• Programs compiled in UNIVERSAL mode will adopt the error mode 
selected at fink time i.e. HALT or STOP mode. If UNIVERSAL mode is 
selected at both compile and link time, then the error behavior vnll default 
to HALT mode. 

By default, C and FORTRAN programs are compiled in UNIVERSAL error mode 
and linked in HALT mode. By default, Occam programs are compiled in HALT 
mode and linked in HALT mode. 



9.4 Debugging configured programs 

Programs configured with the C-style configurer, icconf , must have debugging 
enabled by means of the appropriate icconf command line options, occam 
programs are compiled, linked, and configured with interactive debugging enabled 
by default. Debugging can be disabled in Occam modules by the appropriate 
occonf command line options. 

Table 9.1 summarizes the effects of the relevant icconf and occonf options on 
interactive and post-mortem debugging, and on virtual routing. 
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icconf 

command 

options 


occonf 

command 

options 


Effect 


'g^and 'nv' 


'nv' 


Interactive and post-mortem debugging 
enabled. 

Virtual routing disabled. 

Possible to jump down channels between adja- 
cent processors. 


'g' 


default 
settings 


Interactive and post-mortem debugging 
enabled. 

Virtual routing enabled and will be used even if 
not required, i.e. direct channel placements 
between processors will be ignored. 

Not possible to jump down channels between 
adjacent processors. 


'gp'and 'nv' 


'y'and 'nv' 


Post-mortem debugging enabled. 

Virtual routing disabled. 

Possible to jump down channels between adja- 
cent processors. 


'gp' 


■y' 


Post-mortem debugging enabled. 

Virtual routing enabled and may be used. 

Only possible to jump down channels between 
adjacent processors if they are not used for 
virtual routing. 


Note: the icconf 'gp' and the occonf 'y' options are not equivalent. For further 
details of configuration options, see the Toolset Reference Manual. 



Table 9.1 Effect of icconf and occonf options on debugging 



9.4.1 Debugging with configuration level channels 

idebug cannot locate to a process waiting on a transputer link, or locate to a 
process (on a different processor) waiting on a channel mapped onto a link, if that 
link is used by the configurer for software virtual channels. 

idebug is able to iocate to a process waiting on a transputer link or jump down 
a channel between two processes (which may be on different processors) If the 
channel is one of the following: 

• An internal (soft) channel between processes on the same processor. 

• An external (hard) channel between processes on different processors 
which is not used by the configurer for software virtual links. 
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9.4.2 Debugging wfth the configurer reserved attribute 

The reserved attribute should not be specified to the configurer in order to reserve 
on-chip memory if you wish to interactivefy breakpoint debug the program. This is 
because the runtime kernel (see section 9.7, 1) which the debugger places on each 
processor reserves the first 11K - 15K of memory for its own use (regardless of 
the reserved attribute being specified to the configurer). 

9.5 Debugging boot from ROM programs 

Programs configured using the icconf 'GP' option or the occonf 'Y* option (see 
table 9.1) may also be debugged in boot from ROM run in RAM systems (confi- 
gurer 'RA' option). 

9.6 Post-mortem debugging 

Post-mortem debugging is the analysis of stopped programs, that is, programs 
that have failed to run con-ectly and have set the transputer error flag (or have 
detected a hard parity error). Programs that are to be debugged in this mode 
should be compiled and linked in HALT mode (HALT is the linker default) so that 
the processor halts when the flag is set. They should be loaded by iserver using 
the 'SE' option, so that the error flag is monitored and the server temiinated if the 
en^or flag is set. 

The conditions in which the transputer en^or flag may be set depend on the 
language being used. C and FORTRAN pnDvkie little or no automatic checking of 
errors whereas Occam provides comprehensive error checking by default. 

C programs can also set the error flag and halt the processor when the program 
is terminated by functions such as halt_processor, abort, assert, 
debug_stop or debug__assert. 

9.6.1 C and FORTRAN programs 

Little automatic en-or checking is provided in C or FORTRAN — this can make it 
difficult to cause a program to halt when an error occurs. This rather restricts the 
usefulness of post-mortem debuggingi but it can be used if programs are halted 
explicitly using the debugging support functions such as debug_assert() 
(DEBUG_ASSERT () in FORTRAN) etc. These functions are described more fully 
in the appropriate Language and Libraries Reference Manual and in the debug- 
ging examples. 

Breakpoint debugging, with its associated debugging support functions, is a more 
flexible approach and is the recommended method when debugging C and 
FORTRAN programs. 

The C library abort ( ) function can be enabled to halt the processor by calling the 
auxiliary function set_abort action (). This enables a backtrace to be 
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performed to the point in a program where the error occurred without the need to 
modify any of the assert () statements contained in the program. 

This technique is illustrated with the following example (which is contained in the 
C toolset debugger examples directory): 

^■ktirli-kltlr******************************** 

* 

* Debugger ucaz^l* : abort . c 

* Esuunple of forcing a C program to HALT the 

* processor for poat-mortea analysis regardless 

* of the error mode it has been configured in. 

* 

* Use of the debog support functions is encouraged 

* as an alternative (see debugger exair^le file debug. c 

* for further details) , 

f include <stdio.h> 
lindude <stdlib.h> 
tinclude <misc.h> 
finclude <a8sert.h> 

int 

main {void} 



/* will cause assert () to fail assertion test */ 
int X = 0; 

printf ("Frogran start»d\n'') ; 

/* override normal abort action */ 
set_abort_^action (ABORT_HALT) ; 

printf C^Frogram being halted by assert ()\n'^) ; 
assert (x) ; 

printf (^Program being halted by abort [)\n") ; 
abort () ; 

e^t (EXIT SUCCESS) ; 



9.6.2 Occam programs 

The runtime errors that can cause an Occam program to set the error flag and halt 
include: 
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• An arithmetic en'or, such as overflow or divide by zero, has occurred. 

• An array ihdex is out of range. 

• A value ts out of range in a type conversion. 

• An alignment error has occun-ed in a type conversion or abbreviation 

• An array element is being 'aliased' at mn-time — that is, being referred to 
by more than one name within a given scope. 

• A STOP process, or a process which behaves like STOP (e.g. an IF with 
no TRUE guards, or an alt with no enabled guards), being executed. 

When a run-time en-or occurs, the program halts the processor and allows the 
debugger to enter the program for post-mortem debugging. 

In addition, some debug support functions (e.g. DEBUG, ASSERT () ) are provided 
to aid debugging of programs by implementing an explicit program error; details 
of these functions can be found in the Occam 2 Toolset Language and Libraries 
Reference Manual and in the debugging examples. 

9.6.3 Interrupted programs 

Post-mortem debugging can also be used to debug programs that have been 
explicitly inten^pted with the host system BREAK i^ey. To intenupt a program, for 
example when a program 'hangs', press the BREAK key, which stops the server 
but not the pnagram, and then run idump to take a snapshot of the mnning 
program. Running xdump stops the program by sending an Analyse signal to the 
transputer in order to take a snapshot of its curent activity. 

9.6.4 Parity errors 

The T426 will detect two types of parity errors, hard and soft. A soft error is one 
which disappears on retry; it does not stop the processor but sets, and resets, the 
SoftParityError pin. This allows soft errors to be monitored externally (or inter- 
nally if SoftParityError is connected back to the Eventinput). A hard error occurs 
if a location still causes a parity en*or on retry; in this case the processor is stopped 
immediately and the HardParityError pin is asserted. 

After a hard parity en-or has been detected the debugger can be started in post- 
mortem mode. If the debugger fails to find a processor which has halted with the 
error flag set, it will try to find a T426 processor which has had a hard parity error. 
It will then display this as the first processor in en'or. The debugger does not auto- 
matically locate to the program source if a parity error has occurred — the 
debugger will instead display the monitor page to allow the parity registers to be 
examined. 

The parity registers are displayed on the monitor page at the bottom left of the 
display below the clock registers. These registers are noMisplayed in interactive 
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mode. This is because the registers are volatile and reading the registers would 
interfere with any user code attempting to handle soft parity enors. 

9.6.5 Debugging the root transputer 

Programs which run on the root transputer, or which use the root transputer to mn 
part of a muttiprocessor program, must be debugged 'off-iine' from a separately 
created memory image file. This is necessary because the debugger executes on 
the root transputer and ovenwrites the code in its memory. The memory dump is 
performed using the iduiap tooi after the program has failed and before the 
debugger is started with the *R* option. Details of how to use the idun^ tool can 
be found in chapter 5 of the accompanying Tbo/sef Reference Manual. 

Skip loading 

As an altemative to using the idtaap tool, the application program can be skip 
loaded onto the next processor on the network, avoiding the root transputer. This 
leaves the root transputer free to run the debugger. A disadvantage of this method 
is that it requires one extra processor on the network in addition to those needed 
for the program. 

If only one transputer is available, for example on single-transputer boards, the 
memory dump method must be used. If more than one transputer is available skip 
loading is the recommended method since it enables the program to be directly 
debugged from transputer memory. 

Use of the skip loader is described in chapter 7 of this manual and chapter 15 of 
the accompanying Toolset Reference Manual. 



9.7 Interactive debugging 

Interactive debugging allows programs to be executed under interactive control 
using breakpoints set in the code. Breakpoints can be set on any line of source. 
Symbolic and monitor page facilities can be used to examine code, inspect vari- 
ables, jump down channels to other processes or processors, and determine the 
state of the network. Special symbolic functions and monitor page commands, 
only available in breakpoint mode, support the modification of variables and 
memory tocations and the restarting of programs from the breakpoint or from other 
points in the code. 

Pnagrams that communfcate to the host must use iserver protocol, as used by 
the standard I/O libraries, when being debugged interactively. 



9.7.1 Runtime kernel 

The breakpoint debugger places a special runtime kemel on each processor in 
addi^on to the applk;ation bootable code. This kemel provkles a communication 
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network to enable the debugger to transparently share transputer links with the 
application in addition to providing a breakpoint handler to deal with breakpoints, 
errors, inspection of processor state etc. The scheme is illustrated in Figure 9.2. 

Note: The debugging kernel places the transputer into Halt-On-Eror mode (HALT 
mode) regardless of the en-ormode of the program. This means that during break- 
point debugging a transputer will always halt when an error occurs. 
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Figure 9.2 Debugger runtime kernel 

The runtime kerne! requires a certain amount of memory on each processor, the 
exact amount differing slightly between processor types. Kernels on processors 
with hardware support require slightly more memory because they retain more 
state information. The size of the kernel on each transputer type is given in 
table 9.2. 

Apart from the extra memory required, the kernel is transparent to the application 
program if processes on different processors communicate with each other in the 
normal way, using channels supplied by the configurer 

Note: To allow breakpoint debugging to function con-ectty a program must not 
place channels explicitly onto processor link addresses. Programs that do so may 
introduce conflict with the runtime kernel, which also uses the links. Programs 
currently coded in this way should be re-coded to pass in hard channels, or edges, 
from the configurer, otherwise breakpoint debugging may not be used. 
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Processor 


Kernel size 


H/W support 


M212 


11.25K 


No 


T212 


11.25K 


No 


T222 


11.25K 


No 


T225 


12.75K 


Yes 


T414 


13.5K 


No 


T800 


13.5K 


No 


T400 


15.25K 


Yes 


T425 


15.25K 


Yes 


T426 


15.25K 


Yes 


T801 


15.25K 


Yes 


T805 


15.25K 


Yes 



Table 9.2 Runtime kernel size and processor brealcpoint support 



9.7^ Processors without hardware breakpoint support 

Certain transputers have built-in instructions to aid breakpointing (see table 9.2). 
For those processors without hardware breakpoint support, breakpoints should 
not be set within high priority processes because the mechanism used to imple- 
ment breakpoints causes such processes to lock the processor and disables all 
communications to the processor via the runtime kernel. To help safeguard against 
this problem, the debugger monitor page breakpoint option will only set break- 
points at high priority process entry points ormain ( ) on processors with hardware 
breakpoint support 

The exact effect on the networit of encountering such a breakpoint will depend on 
the position of the processor in the network hierarchy but the possibility should be 
avoided. Since the debugger is, in general, unable to check the validity of break- 
points it is the programmer's responsibility to ensure correct operation on proces- 
sors without direct hardware breakpoint support. 

9.7.3 Creating programs for debugging 

Programs to be debugged using breakpoint debugging should be compiled with 
full debug information enabled, using the C and FORTRAN compilers 'G' option 
and the occam compilers default. 

All modules in the program must be complied in the same^ or a compatible, mode. 
Modes are checked at link time and if incompatible modes are found then the link 
is aborted. 

The code must be produced without using the 'Y' option with any of the tools if inter- 
active debugging is to be done. 
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9.7.4 Loading the program 

Breakpoint debugging does not require spedal loading or memory dump proce- 
dures because the program is automatically skip loaded by the breakpoint 
debugger. However, breakpoint debugging does require one extra processor in 
the network because the root processor is dedicated to running the debugger 

Clearing error flags 

[feitheriserver or idebug detect that the errorflag is set immediately a program 
begins to run» it is likely that the network contains more processors than you are 
currently using, and that one or more of the unused processors has its errorflag 
set. The eror flag may be randomly set when the transputer is powered up — it 
is normally cleared by the bootstrap code. 

The en^or flags of all the processors in a network can be cleared by running a 
network check program such as ispy. This ensures a clean network on which to 
load the program. This generally only needs to be done once, after the system is 
first turned on. 

The ispy program is provided as part of the support software for some INMOS 
iq systems products. These products are availatile separately through your local 
INMOS distributor 

An alternative way of clearing all the error flags in the network is to load a dummy 
program which is configured to use every processor in the network. In the act of 
loading the dummy code the processor emor flag is cleared. 

Parity-checked memory 

In system that include some processors which have extemal memory with parity- 
checking (e.g. systems built wth the T426) it is necessary to initialize the contents 
of memory before the application code is mn. This is because a read from un-ini- 
tialized memory could cause a parity error to be reported. 

Normally, when not breakpoint debugging, the contents of memory are initialized 
by the bootstrap loader code. This is controlled by the collector CM option (see 
chapter 3 of the Toolset Reference Manual). 

The debugger has two command line options which can be used for for memory 
initialization — both of these are followed by a hexadecimal number representing 
the pattern to be written to memory. The *J* option writes the given pattern to all 
of the data areas (stack, workspace, static, heap and vectorspace as appropriate) 
in each processor The 'K' option writes to the same areas of memory as the 'J' 
option and also to the 'treespace' area. 

In general, the 'J' option should be used for configured programs and the 'K" option 
for non-configured programs (i.e. programs for a single processor produced using 
the collector's 'T' option). The memory initialization is performed on all processors 
in the network, not just T426s. 
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These options can also be useful for seeing where data has been written to 
memory. For example, they can be used to determine the size of stack or heap 
used by a program when it runs, or to detect data written to unexpected areas of 
memory. Note that the bootstrap phase of a program may use a small part of the 
program data and freespace areas for its own purposes, consequently the pattern 
of data may have some holes In it. 



9.7.5 Running the debugger 

The command idebug starts the host file server program, iserver, to load the 
debugger onto the root transputer and provide it with host services. Different 
options need to be given to idebug depending on the type of debugging being 
done (e.g. breakpoint or post-mortem) and the details of the transputer network 
being used {e.g. Is the code to be debugged running on the root processor or is 
that transputer available for the debugger). Some basic examples are given here. 

Note that the transputer network is not reset or analyzed by default so, generally, 
one of the iserver options must be specified forthis (e.g. 'SR' or 'SA% This is true 
even if the 1>' option is being used to run the debugger without using transputers 
(because the processor running the debugger must be reset). 

When doing breakpoint debugging, the 'SR' option Is used to cause the iserver 
to reset the transputer network and the 'B' option to specify which link from the root 
transputer is connected to the processors running the application code — for 
example: 

idebug -sr -b 2 program. btl (UNIX) 

idebug /sr /b 2 program. btl (MS-DOSA/MS) 

As another example, when using the debugger in post-mortem mode to debug a 
program which does not use the root transputer, the 'sa' option would be used to 
make the server put the network into Analyse mode with the 'T' option to specify 
the link from the root processor to the transputer running the program to be 
debugged: 

idebug *sa *t 2 program. btl (UNIX) 

idebug /sa /t 2 program. btl (MS-DOSA/MS) 

Finally, when debugging a program running on the root transputer in post-mortem 
mode, the idun^ command is first used to create a file containing a dump of the 
transputer's memory and then idebug is run with the 'R' option to specify the core 
dump filename — for example: 

idump core.dmp #100000 

idebug -r core.dn^ program. btl (UNIX) 

idebug /r eore.dmp program. btl (MS-DOSA/MS) 

Complete detaiis of which options to use in different circumstances are given in the 
accompanying Toolset Reference Manual, chapter 4. 
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9.73 Interactive mode functions and commands 

Several symbolic debugging functions and monitor page commands are only 
available In interactive mode. The commands available are summarized below. 

Symbolic functions 

I TOGGLE BREAK | Set OT dear a breakpoint on the current line. 
I RESUME I Restart a process stopped at a breakpoint. 

I CONTINUE FROM | Restart a stopped process from the current line. 
I iviODiFY I Change the value of a variable in memory. 

Monitor page commands 

[Tl Breakpoint menu. 

[T] Execute program. 

[s] Show debugging messages. 

fu] Update register display. 

[W] Write to memory. 

9.7.7 Breakpoints 

Breakpoints can be set, deared, and listed using monitor page commands, and 
set/cleared using symboJic functions. 

Breakpoints can be set at any point in a process running on any processor. At each 
breakpoint, or on program error, the process pauses and the source code may be 
displayed. 

Note: When a process is stopped at a breakpoint or by one of the debugging func- 
tions {e.g. debug_stop) other parallel processes in the program continue to run. 
A side effect of pausing Is that the debugger suspends iserver communications 
In order to preserve the debugger's screen display. 

Breakpoints can be set at code entry points, or on any line of source code. Vari- 
ables within scope at the breakpoint can be modified and the process restarted. 
Breakpoints can also be set at the monitor page but care should be taken not to 
set breakpoints at addresses that do not correspond to the start of a source code 
statement^ otherwise the behavior is undefined. 

Setting breakpoints at symbolic level is the recommended method. 

9.8 Program termination 

Program termination is signalled to the debugger by the tenninatlon of iserver. 
This is performed automatically by the C and FORTRAN runtime systems, and 
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must be done explicitfy by the user in OCCam code. If the program contains Inde- 
pendently executing processes which do not require communication with the 
server the debugger may be resumed to interact with these processes. 

To run or debug the program again it must be reloaded onto the transputer usfng 
isterver, or idebug in breakpoint mode. 



9.9 Symbolic facilities 

Symbolic debugging is debugging at source code level using the symbols defined 
in the program for variables, constants and channels. Features provided in 
symbolic debugging include the examination of source code, the inspection of vari- 
ables and channels, and the backtracing of procedure calls. A number of special 
breakpoint functions are available ff the debugger is run in breakpoint mode. 

Source level debugging is accessed through s ymbolic functions mapped to 
specific keyboard function keys (e.g, | INSPECT | ) by an 'ITERM' file. Keyboard 
layouts for spedfic terminal types can be found in the Delivery Manual that accom- 
panies this release. Altematively, the comments in the ITERM file can be read to 
find the mapping of functions to keys. 

Help screen 

A help page can be displayed by pressing either [T] or ] HELP ] , this displays the 
following information: 



idebug Synbolic Help SmnBiary 

1-INSPECT 2-CHAS 3-TO? 4-KETKACE S-KZLOC 6-INFO 7-HOD 8-ELESDHE 9-HONITOR 0-EACK 

The above list sumniarises the commonly used functions available in symbolic 
mode. For a complete list of all symbolic functions available please refer to 
the idebug documentation. The mapping of a symbolic function to a particular 
key may be found in the file defined by the ITERM environment variable, 

IHSPECT - Display the type and value of a variable 

CHANNEL - Locate the process waiting on a channel 

TOP - Locate back to the error or last source code location 

RETRACE - ando a BACKTRACE 

RELOCATE - Locate back to the last location line 

IHFO - Display process information (eg. Iptr^ Wdesc, process najne) 

MODI FY - Change the value of a variable in memory 

RESUME - Resume a process Stopped at a breakpoint 

MONITOR - Change back to the Monitor page 

BACKTRACE - Locate to the calling fiinction or procedure 

HELP or ? - This help summary 



Hit any key to continue 



The main symbolic debugging activities and the functions that are used to access 
them are described in the following sections. 
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9.9.1 Locating to source code 

Locating to the source code for a particular process is a crucial procedure [n the 
debugging process on which other operations depend. For each required location 
the debugger must be given a memory address which it uses to locate to the 
source. When the required code is located, symbolic functions can be used to 
browse the code and inspect variables. Where the source code is unavailable, for 
example, libraries supplied as object code with minimal debug information, the line 
containing the library call is located to instead. 

When first started in post-mortem mode, the debugger determines the address of 
the last instruction executed, which it uses to automatically locate to the relevant 
source code. Subsequently for each new point to locate to in the code the 
debugger requires a new address which can be supplied by the programmer 

Process addresses can be determined using the monitor page [r], [T], and |X] 
commands that display the processes waiting on the run queues, the timer 
queues, and the transputer links. To locate to a process displayed by one of these 
commands, use the[G] command. Code coresponding to any memory address 
can be located using the monitor page [o] command. 

Certain addresses are already known to the debugger and can be located to using 
symbolic functions without specifying the address or switching to monitor page 
commands. Many of the common operations used during source code debugging 
can be perfonned directly with symbolic functions. They include relocating to the 
previous location, locating to the original error, and locating to a process waiting 
on a channel. 

The symbolic functions that can be used directly for locating to specific locations 
and sections of source code are listed below. 



I RELOCATE | Locate back to the last location line. 

I TOP I Locate back to the enor or last source code location. 

I CHAMNEL ] Locate to the process waiting on a channel. 

The I CHANNEL I function is described more fully in section 9.9.4. 

Otherfunctions which locate to specific sections of code are the | backtrace | and 
I RETRACE I functions. These are used to trace subprogram calls and do not require 
a specified address. The functions are described in section 9.9,4, 

A strategy for locating processes in multi-process programs is presented in 
section 9.11. 

9.9.2 Browsing source code 

Several functions are available for browsing source files once they have been 
located. They include functions for navigating files, changing to included or new 
files, and string searching. The functions are listed below. 
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[ TOP OF FILE" 
[ END OF FILE" 
I G0T0LINE~1 



iSEARCH 



ENTER FILE 



EXIT FILE 



Go to the first line. 

Go to the last line. 

Go to a specified line. 

Search for a specified string. 

Enter an included source file. 

Exit an included source file back to the endosing source 
file. 



CHANGE FILE | Display a different source file. 



9,9,3 Inspecting source code and variabies 

The values of constants, variables^ parameters, an'ays, and channels can be 
inspected at any point in the code. A special inspect function for channels allows 
the debugger to locate to the process waiting at the end of the channel. Symbols 
to be inspected must be in the scope of the source line last located to. 



INSPECT 



I CHANNEL I 
I TOGGLE HEX" 



I GETADDRESSi 



INFO 



Display the type and value of a source code symbol, 

Locate to the process waiting on a channel. 

Enables/disables Hex-oriented display of constants and 
variabtes. Selects the display of source code symbols in 
hexadecimal form for C and FORTRAN. 

Displays the start address of the sequence of transputer 
instructions corresponding to the selected source line. 

Displays low-level information about the selected process. 



9.9.4 Jumping down channels 



The I CHANNEL [ function can be used to locate to a process waiting on a channel. 
This is known as 'jumping down' a channel and works for channels on the same 
processor (internal or soft channels) or channels assigned in the configuration to 
transputer links (external or hard channels which connect processes on different 
processors together). It cannot be used to jump down software virtual links 
provided by the configurer. Debugging can then continue at the waiting process. 
If no process is waiting on a channel the channel is reported as 'Empty', 



9,9.5 Tracing procedure calls 

Two functions assist in the tracing of procedure and function calls. They can be 
used even if the source of the called routine is not present, for example, libraries 
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supplied as object code with mmimal debug information. In this case the line 
containing the function call is displayed rather than the library code itself. Where 
procedures are nested, successive backtrace operations will locate to the original 
call. Variables and othersymbols can be inspected at any stage. The two functions 
are listed below. 

fBACKTRACl"! Locate to the calling procedure or function. 



RETRACE I Undo a I BACKTRACE 1. 



9.9.6 Modifying variables 

The I MODIFY I function allows variables to be changed in transputer memory and 
the program continued with th e new value s. For C and FORTRAN it supports the 
same expression language as | inspect | . For further details see chapter 4 in the 
Toolset Reference Manual, 



9.9.7 Breakpointing 

Symbolic functions are provided for setting and clearing breakpoints, for modifying 
the value of a variable, and for continuing the program. 



I TOGGLE BREAK | Set or clear a breakpoint on the current line. 
[resume ] Restart a process stopped at a breakpoint. 



CONTINUE FROM | Restart a stopped ppDcess from the cun^ent line. 



imterruptI Force the debugger into the monitor page {without neces- 

sarily stopping the program). 



I MODIFY I Change the value of a variable in memory. 

9.9.8 Miscellaneous functions 

The following extra functions are available at symbolic level: 



MQNtTQR I Change to the monitor page. 



FINISH I Quit the debugger. 



9.10 Monitor page 



The debugger monitor page is a low level debugging environment which gives 
direct access to machine level data. It allows memory to be viewed and disas- 
sembled and gives access to information about the processor's activity through 
the display of en'orflag status and pointers to process queues. Specific debugging 
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operations are selected by single letter commands typed after the 'Option' 
prompt. 



9.10.1 Startup display 

When first started in interactive mode, or in post-mortem mode with an Invalid Iptr 
or Wdesc (see below), the debugger enters the monitor page environment and 
displays Information such as the addresses of instruction and workspace pointers, 
status of emDrflags, and information about the pnacessor run queues. The memory 
map is also displayed. 

If an iptr or Wdesc is invalid at startup It is indicated by an astensk {'*'), A double 
asterisk ('**') is used to indicate an Iptr or Wdesc which is outside the defined 
memory on a processor (i.e. beyond the 'freespace'). 

The monitor page display differs slightly between post-mortem and breakpoint 
modes. In post-mortem mode the display includes the saved pointers for the low 
priority process if the processor was running at high priority when analyzed; in 
breakpoint mode the display does not include these pointers but does include the 
contents of the registers Areg, Breg, and Creg, if known. At startup in breakpoint 
mode, no machine pointers or register values are available (the program has not 
yet started) and so no values are displayed. 

A typical startup display is shown In Figure 9.3. 



Toolset Debugger : V4.00. 


00 Processor 


"' IT426) 




Processor State 


Memory 


nap (Postmortem Made) 




Iptr 


#8OOOO10C 


* Configuration code 


; tSOOOOOTO - +soaooi4F C 


224 ) 


Wdesc 


Hot Process 


Stack 


: #80000150 - +&OOO0SEF { 


1&04 ) 


Error 


Clear 


Program code 


: I80000BC0 - +80004373 ( 


i6K) 


Halt On Error 


Set 


Static area 


: 180004574 - #S0Q04E27 { 


2228 ) 


Fptrl (low 


Empty 


Configuration code 


: #80004E2S - #S00047E7 ( 


443 ) 


Bptrl queue) 




Freespace 


: f80004FE8 - #BOOFFFFF ( 


1005K) 


FptrO <high 


Empty 








BptrO queue) 




Total memory usage 


: 23912 bytes (24K) 




Tptrl (timer 


Empty 








TptrO queues) 


Empty 


On-chip memory (4K) 


: *BO0OQOOO - JSOOOOFFF 




Clockl (low} 


#000C2DD6 


MemStart 


: #90000070 




ClackO (high) 


#030BT57C 








ParityError 


Hard 1011 


Debugger has enough 


memory for 233 processors 




ParityAddr 


#aD005DF0 









Last instruction was : in 

Option (? for help) (A,C,D,E, F,G,H, IrK, L,M,H,0, P,Q,B,T, V,X, ?) ? 



Figure 9.3 Example post-mortem startup display for a T426 processor 

Items displayed on the startup page and their meanings are summarized in 
table 9.3. Most of the data displayed is common to all transputer types. Where the 
display differs for specific processor types and debugging modes, this is indicated 
in the table. 
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Item displayed 


Description 


Iptr 


Instruction pointer (address of the last instruction 
executed). 


Wdesc 


Process descriptor (process priority and workspace 
pointer). 


IptrlntSavet 


Saved low priority instruction pointer, if applicable. 


WdeselntSavet 


Saved low priority process descriptor, if applicable. 


A Regiaterit 


Contents of A register, if known. 


B Register^ 


Contents of B register, if known. 


G R«gister$ 


Contents of C register, if known. 


Error 


Status of transputer error flag. 


FPU Error 


Status of FPU enxjr flag (T80x series only). 


Halt On Error 


Status of halt on en-orflag. 


Fptrl 


Front pointer to low priority process queue. 


Bptrl 


Back pointer to low priority process queue. 


FptrO 


Front pointer to high priority process queue. 


BptrO 


Back pointer to high priority process queue. 


Tptrl 


Pointer to low priority timer queue. 


TptrO 


Pointer to high priority timer queue. 


Clockl 


Value of low priority transputer clock. 


ClockO 


Value of high priority transputer clock. 


ParityErrort 


Status of parity error register, if applicable. 


ParityAddrt 


Address of parity en-or, if applicable. 


t Not available in breakpoint mode. 

t Not available in post-mortem mode. Not known to the debugger in break- 
point mode on processors with no hardware support for breakpoint! ng. 



Table 9.3 Data displayed at the monitor page 
Process Workspace or Stack 

A process woricspace (or stack) consists of a vector of words in memory. It is used 
to hold local variables of the process. The workspace Is organized as a falling 
stack, with 'end of stack' addressing; that is the local variables of a process are 
addressed as positive offset from the wori<space pointer (Wptr). 

Process Descriptors 

In order to identify a process completely, it is necessary to know both its wod^space 
pointer Wptr (in which the byte selector Is always 0), and its priority (which is for 
high priority and 1 for low priority). A process descriptor, Wdesc, is the sum of the 
process's workspace pointer, Wptr, and its priority. 
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Process pointers 

Iptr points to the last instruction executed and Wdesc contains the process 
descriptor. Ttie saved low priority Eptr and Wdesc are also displayed if the 
processor was running a high priori^ process when it was halted. An asterisk 
placed next to either an Iptr or Wdesc indicates an invalid memory location for the 
process. A double asterisk indicates that the address is outside the defined 
memory map of the processor. A Wdesc value of 'NotProcess' indicates that no 
process was executing on the processor when it halted 

Practical notes: 

• If Wdesc contains the value 'MemStart' it is likely that the Analyse signal 
has been asserted more than once on the network. This can occur on 
transputer boards where the subsystem signal is asserted on analyze, as 
on the IMS B004. For further guidance on the use of such boards refer to 
chapter 4 in the accompanying Toolset Reference Manual. 

• If Wdesc contains the word 'NotProcess' it means that there were no 
runnable processes at that instant on the transputer (check timer and 
external links for any waiting processes) — this may also occur in the pres- 
ence of deadlock. 

• If WdesclnfSave contains the word 'NotProcess' it means that a low 
priority process was not intenupted when the high priority process started 
running. 

Fptr and Bptr point to the process mn queues, which hold information about 
processes awaiting execution. The suffix indicates the high priority queue and 
the suffix 1 indicates the low priority queue. 

If the frontand back pointers are the same then only one process is waiting; if there 
are no pnxesses waiting the pointers have no value and the queue is shown as 
'Empty'. 

TptrO and Tptrl are pointers to the high and low priority timer queues respectively. 

Registers 

In breakpoint mode only, the contents of the transputer registers Areg, Breg, and 
Creg are displayed for those processors which have built in instrudions for break- 
point handling {see table 9.2). Values displayed are those which were current 
when the process stopped. 

Error flags 

Two flags are displayed for all processors: Error and HaltOnError. The FPError 
flag is also displayed for transputers with an integral floating point unit (IMS TSOx 
series). 
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Clocks 

ClockO and Clockl display the values of the high and low priority clocks when the 
process was stopped. In breakpoint mode the clock values, queue pointers and 
link infomnation can be updated using the monitor page [u] command. 

Parity errors 

ParityError and ParityAddr are only displayed for a T426 processor in post- 
mortem mode. ParityError is the state of the Parity ErrorReg and can contain one 
of the following: 

Soft xxxx A soft parity en^or has occun-ed 

Hard xxxx A hard parity error has occun'ed 

The value xxxx shows the byte selector bits of the en-or registers; the value 
is in binary with byte 3 on the left through to byte on the right. Thus, the value 
1011 would show that bytes 3, 1 , and are in error. 

NotlnMem The memory in a dump file does not include the parity registers 

Clear No parity error has occun'ed 

ParityAddr shows the state of the ParityErrorAddressReg and can contain one 
of the following: 

Uhhhhhhhh Word address, in hexadecimal, of location where en^or occun-ed 
NotlnMem The memory m a dump file does not indude the parity registers 
Undefined No parity error has occurred 

Memory map 

The memory map display is included on the standard startup display — this is the 
same memory map as displayed by the monitor page [¥] command. Any or all of 
the following memory segments may be displayed, depending on the application 
program and its configuration: 

Runtime kernel 
Reserved memory 
Configuration code 
Stack (Workspace) 
Program code 
Vectorspace 
Static area 
Heap area 
Configuration code 
Freespace 
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When the memory map is displayed, the mode Wiatthe debugger is running in is 
shown. This will be one of: 

Interactive Mode When interactively debugging a program. 

Postmortem Mode When debugging a program in post-mortem 

mode. 

Interactive Postmortem When post-mortem debugging a program which 

was previously debugged interactively. 

Dummy Session When the debugger is started with the D 

command line option. 

9.10.2 Monitor page commands 

Most monitor page commands are single-ietters that are typed at the monitor page 
Option prompt A few commands are mapped onto specific function keys. The 
commands that support breakpoint debugging are only available when the 
debugger is mn in interactive mode. 

The main monitor page commands allow you to disassemble and display trans- 
puter memory, locate and debug processes, and examine the network processor 
by processor. 

The main commands for common debugging operations are introduced in the 
following sections. Full details of all the commands can be found m chapter 4 of 
the accompanying Toolset Reference Manual. 

Examining memory 

Specific segments of transputer memory can be displayed in hexadecimal, ASCII, 
any high level language type, or disassembled into transputer instructions. The 
segment of memory to be displayed is specffied by a starting address. A map of 
the transputer's memory can be displayed giving the positions of code and work- 
space. Commands for examining transputer memory are summarized below. 

[X] Display memory in ASCII. 

\~d] Disassemble into transputer instructions. 

[W] Display memory in hexadecimal. 

p~| Display memory in selected data type. 

[W\ Memory map. 

Locating processes 

Locating to code for specific processes is one of the major functions available 
through the monitor page. The commands available allow processes other than 
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the stopped or current process to be located and examined anywhere on the 
network. Processes can be located on the current processor by examining mn 
queues, and on other processors by jumping down transputer links. 

Four commands are used, three to display waiting processes and one to jump to 
the selected code of a process displayed by the other three. 

\W\ Display processes waiting on Run queues. 

[T] Display processes waiting on Timer queues. 

rn Display processes waiting on transputer Links. 

[Y] Display processes waiting on software virtual links. 

[g~\ Goto symbolic debugging for the selected process. 

These commands can be used to trace all processes on a network and determine 
the cause of program failure. The method is explained in more detail in 
section 9.11. 

Specifying processes 

The [o] command allows a specific process to be selected for symbolic debug- 
ging, providing the address is known. 

fo] Specify a pn^cess for symbolic debugging. 

This command is useful for switching directly to symbolic debugging for a process 
whose instruction pointer and process descriptor you have already noted, earlier 
in the debug session. 

Selecting processes 

The [T] command enables a source file to be selected for symbolic display using 
the filename of the object module produced for it 

rn Select a source file to be displayed. 

This option enables symbolic locating (for setting breakpoints etc.) without 
needing to know iptr and wdesc process details (as the [g] and [o] commands 
do). 

Other processors 

Two commands and two cursor keys allow other processors to be selected. 
\~e] Go to next halted processor 

rn Go to specified processor. 
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f4\ Go to the next lowest numbered processor 

[►1 Go to the next highest numbered processor. 

The sequence of processors used by the [T] and cursor key commands is an 
internal sequence read by the debugger. Processor numbers corresponding to 
visible names in the configuration file can be determined by using the \~k] 
command. 

Breakpoint commands 

The following commands support breakpointlng. To use these commands the 
debugger must be run with the 'b' command tine option. 

[b~\ Breakpoint menu. 

[jj or I resume"] Jump into and run application program. 

[T] Show debugging messages and prompts menu. 

[U~\ Update processor status display. 

\W\ Write value to memory. 

Changing to post-mortem debugging 

When a program crashes during interactive debugging you are able to change to 
post-mortem debugging using the following command: 

fYl Postmortem debug current breakpoint session. 

9.11 Locating processes 

Most transputer programs consist of several processes running in parallel, either 
on the same transputer or on separate processors connected by their INMOS 
links. 

If a program en^or halts the transputer then the debugger automatically locates to 
the stopped process, which can then be examined directly. If the program runs 
incorrectly but does not halt the processor, a good approach is to locate to and 
examine each process in tum. 
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There may be many processes running on the transputer when it is interrupted 
from the keyboard, or the idump tool is mn to create a dump file for debugging. 
Each process exists in one of a number of possible states: 

• Not yet started, 

• Running on the processor 

• Waiting on a process execution queue (Run queue). 

• Waiting on a timer queue, 

• Waiting for communication from another process on the same processor. 

• Waiting for communication on a transputer link (Linl< information). 

• Interrupted by a high priority process. 

• Already stopped or terminated. 

9.11.1 Running on the processor 

One, and only one, process may execute on the transputer at any Instant. The 
debugger will automatically locate to this process (if there was one) when the 
debugger is executed. All other processes are either waiting, stopped, or not yet 
started. 

9.11.2 Waiting on a run queue 

Processes on the run queues {I.e. waiting to be executed) can be located by first 
using the monitor page [r] command to display the list of waiting processes. A 
process can be selected from the list by pressing [g] {for 'Goto process'), moving 
the cursor to the appropriate address, and then pressing | reTurm [ . Processes 
can also be located to by specifying the displayed Iptr and Wdesc with the[~o] 
command. 

The values displayed with the [^ command can be used to determine the overall 
status of mn queues. If no processes are waiting then the content of the queue is 
shown as 'Empty'. If pointer addresses are displayed then there are processes 
waiting; If the front and back pointers have the same value then there is only one 
process waiting. 

9.1 1 .3 Waiting on a timer queue 

Processes waiting for a specified time are placed on the high and low priority timer 
queues. These are similar to the run queues except that they are controlled by the 
transputer docks. 
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In a similar way to processes on the Run queues, processes on the timer queues 
can be located by using the monitor page [T] command to display a list of 
processes and then using the [g] command, or by specifying the process 
address. Pointers to the timer queues indicate overall q ueue status in a similar way 
to the run queues. 

9.11.4 Waiting for communication on a link 

Processes waiting for a hardware communication (input or output on a transputer 
linl(, or an input on the Event pin) can be located by using the monitor page [V] 
command to display a list of waiting processes, and then using the[G] command 
to locate to the process. Links where no processes are waiting are shown as 
'Empty*. 

At most 9 processes can be waiting for a hardware communication, two for each 
of the four links and one on the Event pin. 

See section 9.4.1 for information on the restrictions on locating down hard chan- 
nels. 



9.11.5 Waiting for communication on a software virtual link 

Processes waiting for a communication on a software virtual link (as provided by 
the configurer) can be located by using the monitor page [Y] command to display 
a list of waiting processes, and then using the [G] command to locate to the 
process. Virtual links where no processes are waiting are shown as 'Empty'. 

This is the preferred method for locating processes waiting on external commu- 
nications when software virtual links are present 



9.11.6 Waiting for communication on a channel 

Processes wai tJng for a co mmunication on a channel can be focated from source 
level using the | CHANNEL | function. This function works for both internal (or soft) 
channels and extemal (or hard) channels (channels mapped onto processor 
links). 

Only one process can be waiting on a channel. If no process is waiting, the channel 
is shown as 'Empty'. 



9.11.7 Interrupted by a high priority process 

A low priority process may have been intenupted by a high priority process. Such 
a process may be selected using the[G] or[b] commands and the values stored 
in the WdescIntSave location. 
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9.11.8 Processes terminated or not started 

Processes which have stopped executing, or not yet started, do not have process 
descriptors and so they cannot be examined by the debugger. If the currently 
running process and all the waiting processes have been found (not forgetting afl 
those processes waiting on all the inlemal channels) then any processes still unac- 
counted for must either have already finished or failed to start. 



9.11.9 Locating to procedures and functions 

When a pnDcedure Is called, the workspace pointer is moved. If the debugger 
locates inside any code of defined scope (such as a procedure) then only local vari- 
ables, and variables declared globally, are in scope and available for inspection. 

To inspect vari ables or channels not in scope within the procedure or function, use 
I backtrace] to locate to a position where the desired variable or channel is in 
scope. To relocate back into the procedure or function use | retrace | to undo 
each backtrace, or I top I to return to the initial location. 



9.12 Debugging support library 

Three routines are provided in the libraries to assist with debugging. These provide 
the functions stop, assert, and message. The routines have different names for 
each language and are described in more detail in the appropriate Language and 
Libraries Reference Manual Table 9.4 summarizes the routines for each 
language. 



Routine 


Description 


debug_assert C 
DEBUG .ASSERT OCCam 
DEBUG_ASSERT FORTRAN 


If the parameter evaluates to false then stop 
the process and inform the debugger 


debug_stop C 

DEBUG. STOP Occam 

DEBU6_ST0P FORTRAN 


Stop the process and mform the debugger 


debug_message C 
DEBUG. MESSAGE OCCam 
DEBUG_MESSAGE FORTRAN 


Insert a debugging message in the program. 



Table 9.4 Debug support functions 

The stop and assert routines are used to stop a process, the latter on the failure 
to meet a specified condition; such events are treated as a program error by the 
debugger. The message is used to insert messages that will only be displayed 
when the program is run under the interactive debugger. 
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For C and FORTRAN the procedures are included in the standard library that is 
incorporated at linlt lime and are directiy accessible from the program without 
further action by the programmer For Occam programs, the library debug, lib 
must be referenced with a #US£ in the source code and also included as an input 
to the linker. 

in the following descripb'ons the C versions of the functions are used; the descrip- 
tions apply equally to the respective Occam and FORTRAN versions. 

debug_assert() and debug_stop() allow a process to be stopped at any 
point In the code, where it can then be debugged using the symbolic functions and 
Monitor page commands. debug_stop{) always stops the process whereas 
debug_assert {) only stops the process if the parameter evaluates to false. 

debug_mes3age() is used to insert debugging messages into the code. 
Messages are relayed back to the terminal from any point in the program, even 
from code running on distant processors of a network. It can be used to monitor 
the activity of outlying processors which are not directly connected to the host. The 
display of debug messages at the terminal is controlled by an option on the Monitor 
page Breakpoint Menu {the default is io display them). Note: Only the first 80 char- 
acters of a message are displayed. 

9.12.1 Examples 

The use of the debug support functions is illustrated in the C and occam examples 
below. Sources may be found in examples/manuals/idebug. 
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C example: 

* 

* Debugger example: debug. c 

* 

* Elxaii3>le of debug support functions vfaen used vith 

* acid without the debugger. 

* {see also debugger example file abort. c] 

* 
***************************************/ 

#include <stdio.h> 
#include <stdlib.h> 
fincludA 'Onisc.h> 

lut 

main (void) 

{ 

/* will cause debug_as3ert {) to fail assertion test */ 
int X = 0; 

printf ("Program 3tarted\n") ,- 

debug_inessage ("A debug message only within the debugger''] ; 

printf ('^Program being halted by debug_assert ()\n'0; 
debug__aasert (x) ; 

printf ("Program being halted by debug_stop ()\n"); 
debug_stop (} ; 

exit (EXIT_SaCC:ESSJ ; 

} 

In this example, if x is 1 debug_as3ert evaluates to true and the program runs 
until it encounters debug_s top. If x is (as in the example) debug_as3ert eval- 
uates to false and the process stops before it reaches debug_stop. Code 
stopped by debug_assert and debug_stop may be resumed from the line 
following the call of the debug function using the | CONTINUE FROM | key. 
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Occam example: 



— Dabo^gAr axaiiq>l*: dabug.occ 

— EscAapl* of dabug support proc*dur*fl if)i«n a**d with 

— and without tha dmiyjqqmz. 



lINCLnDI "hoatlo.lnc'' 
#naK 'Tioitio.llij'' 
#USK '^dabUff-Hb" 

PROC daituq.tntxy [CHAM OF SP fa, f, []im fr««.iBwory» 
8001. X ; 
SSQ 

~ FAI.se will CM-amm DSBDG. ASSERT to fall aaaartion taat 

X :- FALSI 

ao.writt.atriiig.nl (fa, ta, "Program atart*d"> 

DEBUG. HSSS AGE ("A dabug TB»M»*g* only within th* dabuggar") 

ao.writa.atrlng.nl (fa, ta, 'Frogran baing haltad by DEBDG.ASSXKT (}"} 
DBBDCASSIKI (x) 

ao.wTit«,atring,bI (fa, ta, 'Program baing haltad by DEBDG. STOP ()") 
DEBDG.STOP () 

ao . axit (fa, ta ^ apa . auecaaa) 



in this example x is set to FALSE, therefore debug. assert evaluates to FALSE 
and the process stops before it reaches DEBDG.Stof. Tf x were set to TRUE 
DEBUG, ASSERT woulcl evaluate to TRUE and the program would run until it 
encountered debug. STOE Code stopped by DEBUG. ASSERT or DEBUG, STOP 
may be resumed from the line following the call of the debug function using the 



com^ihruE fromH key. 



9.12.2 Actions when the debugger Is not available 

If the debugger is not available on the system the debug library procedures have 
the following actions: 



debug assert 
DEBUG. ASSERT 
DEBUG_ASSERT 


If the parameter evaluates to false then stop the process 
(also stops the processor if configured in HALT mode). 


debug stop 
DEBUG. STOP 
DEBUG_STOP 


Stop the process (also stops the processor if configured in 
HALT mode). 


debug message 
DEBUG. MESSAGE 
DEBUG_MESSAGE 


No action. 
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9.13 Debugging with xsim 

The T425 simulator isim provides a single processor interactive simulation of a 
program running on an IMS T425 transputer, on a boot from link transputer board 
connected to a host computer through the host file server iserver. The interac- 
tive environment provides a machine level (non-symbolic) environment, similar to 
the debugger monitor page, for debugging programs and monitoring program 
execution. 

The simulator allows any single processor program to be run and analyzed without 
a transputer board. All the component parts of a program to be simulated, must 
be compiled for the T425 transputer type (or compatible class — see appendix B 
of the accompanying Toolset Reference Manual). 

Note: The simulator can only be used to simulate single transputer programs. 

9.13.1 Command interface 

The simulator has a single command interface which con^esponds to the debugger 
monitor page. Most commands are single letter commands and can be executed 
with a single key press. For a list of commands see chapter 14 in the accompa- 
nying Toolset Reference Manual. 

9.13.2 Using the simulator 

The simulator can be used in two ways: 

• To debug programs by inspection of the transputer and memory, in the 
same way as with the debugger Registers, memory, and machine state 
can be examined directly at the monitor page, 

• To monitor the execution of programs using machine level single step 
execution and the setting of break points at specific memory locations. 
Code can be executed by stepping single transputer instructions. 

9.13.3 Program execution monitoring 

The simulator provides a number of functions that can be used interactively to 
monitor and control the behavior of a program. These are: 

• Breakpoints 

• Single step execution of a program 

Breakpoints 

Breakpoints can be set, displayed, and cancelled using the 'B' command to display 
the Breakpoint Options Page. 



72TDS366 01 March 1993 



9 Debugging transputer programs 147 



Single step execution 

A program can be stepped a single transputer instruction at a time using the 'S' 
command. 

9.13.4 Core dump file 

isim may be used to produce a core dump file that can be read by the debugger 
(as if the code had been executed on a real transputer and the memory dumped 
using the idump tool). 

9.14 Hints and further guidance 

This section gwes some further guidance on some specific points related to use 
of the debugger. 

9.14.1 Invalid pointers 

The debugger checks process instruction pointers (Iptr) and process descriptors 
(Wdesc) for the correct code and data limits. Invalid pointers are flagged by an 
asterisk (*) on the screen. Invalid pointers outside the processor's memory are 
flagged with a double asterisk {'**'). 

Invalid pointers can indicate a major problem with the program. They may also be 
caused by specifying an incon^ect dump file. 

9.14.2 Examining and disassembling memory 

Within the monitor page environment, the debugger keeps a record of two memory 
addresses; the start address of the last disassem biy, used as the default by the [d] 
command, and the address of the last region of memory to be displayed, used by 
the [X], [W\ and [T] commands. 

This allows you to switch easily between code disassembly and memory display. 
You can, for example, disassemble a portion of memory using the [d] command, 
examine its workspace in hex using the [W\ command, and then return to the orig- 
inal address by using the [D] command once again. 

9.14.3 Scope rules 

The debugger can only display variables that are in scope at its current location 
point in the source code. 

9.14.4 Inspecting soft configuration channels 

Soft channels declared at the configuration level (i.e. those internal to a processor 
which are not placed on its external links) may be inspected from the monitor page 
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by knowing that they are located near the beginning of the Configuration code area 
which appears after the user Program code area {as displayed by the monitor page 
Memory map command). 



9.14.5 Locating to IF, ALT and CASE in occam 

IF and ALT constructs with no TRUE guards, and CASE constructs where no selec- 
tions are matched, stop the program as though a STOP statement had been 
encountered. In cases like these there is no obvious statement to locate to and the 
debugger locates instead to the start of the construct. 

When using these constructs it is good practice to always define the default case. 
The debugger can then locate directly to the STOP statement where the error 
occurred. 



9.14,6 Analyzing deadlock 

Deadlocks that occur in multitransputer networks can be debugged by using the 
Monitor page 'L' command to examine processes on the transputer links. Dead- 
locks in single transputer programs are more difficult to debug because there is 
no way to enter the program; there are no active processes from which to inspect 
channels, and no links to other transputers to provide an alternative entry point. 

In practice, it is often obvious to the programmer which channel or channels are 
causing deadlock, and a dummy process can be added to the program to provide 
an entry point for the debugger. This is illustrated below using Occam; programs 
could be similarly written in C or FORTRAN. 

Sources may be found in exan^les/i&anuals/idebug. 
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Consider the following code which creates a deadlock: 



— Debugger example : deadlock . occ 

— Example of deadlock. 



#INCLUDE '^hostio.inc" 
#USE "hostio.lib" 



PROC deadlock. entry (CHAN OF SP fs, ts, []INT free, memory) 



PROC deadlock 


{) 


CHAN OF INT 


c 


PAR 




SEQ 




c r 99 




c ! 101 




INT X : 




SEQ 




C ? X 





<^ Missing second input 



SEQ 

deadlock () 

so. exit (£s^ tSr sps. success) 
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The program can be debugged by adding a process that will remain idle (here, 
waiting on a TIMER) while the program is debugged. An example of the type of 
code that is required is illustrated below. 



— Debugger example: deadfix.occ 

— Exainple of deadlock and how to psovide 

— debugging support. 



fINCLUDE "hostio.inc" 

#aSE "hostio.lib" 
#DSE "debug, lib" 



PROC deadfix. entry (CHAN OF SP f», ta, []INT free. memory) 



PROC deadlock 


. debug { ) 


CHAH OF IHT 


c : 


CHAN OF INT 


stopper : 


PAR 




DEBUG. TIMER (stopper) 


SEQ 




PAR 




SEQ 




c ! 


99 


c ! 


101 


INT X 


; 


SEQ 




c ? 


X 


— 


<== His sin 



Hook for debugger 



Hissing second input 
stopper ! — terminate DEBUG. TIMER 



SEQ 

deadl ock . debug ( ) 

so. exit (fSr tSr sps. success) 



The procedure debug . timer is supplied in the Occam debugging fibrary. Similar 
routines could be written for other languages, and the principle of operation is the 
same - the process lies dormant on the processor's timer queue waiting for a time 
as far into the future as the processor can provide. When the timeout expires, the 
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process places itsetf bade on the timer queue. Such a process prowdes a hook into 
the program for locating deadlocked processes because the process is always 
accessible to the debugger on the timer queue. By locating to it you can access 
variables which are in scope at the point of its execution and thereby detect the 
deadlock. In the modified program a deadlock still forms in the procedure, but there 
is now a way to enter the program. 

To enter the program and inspect the deadlock, first invoke the Monitor page envi- 
ronment, and use the Monitor page 'T' command to inspect the transputer's timer 
queue, on which there will be a process waiting. Use the 'G' command to go to that 
waiting process, and the debugger will locate to the calf of debug, timer. 

You can then use | inspect | to examine the channel c where the program has 
deadlocked, and which will therefore contain the process that is waiting for 
communication. Finally you can use | CHANNEL | to jump to the deadlocked 
process. 

The compiler does not insert this kind of debugging code automatically, for several 
reasons. Firstly, it is the philosophy of the toolset that the runtime code should not 
be needlessly altered. Secondly, most programs use many channels, and the 
execution overheads and code size could become unacceptably large. Again for 
the above example code this would be unimportant because the process 
consumes no CPU time, but this may not always be true. Lastly, it could be difficult 
to distinguish the tme deadlocked process from the many idle debug processes 
waiting on the timer queues. 



9.15 Points to note when using the debugger 

This section contains some extra fnfonnation which may be of use when using the 
debugger. Sections 9.15.1 to 9.15.18 apply to debugging in all languages; section 
9.15.19 gathers together those aspects which app^y only to C. 

9.15.1 Abusing hard links 

Current generation transputers permit unsynchronized transfer of messages on 
extemal channels (links). This allows, for example, two 4-byte messages to be 
sent and for them to be received as a single 8-byte message on the receiving trans- 
puter. This is not consistent with the communk^tion of messages between 
processes on the same processor where the transfer of messages is synchro- 
nized. 

When breakpoint debugging, extemal communications are handled by the debug- 
ger's virtual link system; this involves an internal transfer which will function incor- 
rectly if user code is relying on unsynchn^nized transfers. Unsynchronized data 
transfer should not be used where breakpointing is used to debug a program. It 
is bad practice anyway and will certainly cause the virtual link system (used by both 
the debugger and the virtual-rout'ng configurer) to crash. 
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9.15.2 Examining an active network (the network is volatile) 

When a process stops at a breakpoint you should remember that all of the other 
processes are still running (uniess they hit a breakpoint, terminate etc.). This 
means that data displayed by any of the monitor page commands that display 
process queues, etc. (e.g.[R],[T],[T3etc.) may change if they are re-displayed 
(e.g. by using the same command again orthe[¥], Update, command to update 
the displayed Infonnatlon). 

When in symbolic mode the same Is true for channels whk;h may appear empty 
when first inspected only to change to a waiting process when inspected again. 
The only way to effectively freeze all processes is to flip to post-mortem mode by 
using the monitor page \Y] (Enter Postmortem Mode) command. You should 
remember that when you use this command that ail processes that have hit a 
breakpoint will not appear in the runtime queues. If this Is a problem, you should 
note the Iptr and Wdesc values of the processes and, when in post-mortem 
mode, use the monitor page [o] (Select Process) command to locate to them 
symbolically. 



9.15.3 Using | INSPECT | with channel communications 

When debugging a program compiled for interactive debugging it should be 
remembered that channel communication is achieved via library calls. As a conse- 
quence, the I INSPECT 1 key may display an Iptr relating to code in the debugging 
kernel system rather than the Iptr of a user process waiting on the channel. This 
may lead to several channel communications appearing to having the same 
process Xptr (the wdesc will be valid and unique). In order to con'ectly establish 
the Iptr of the process waiting at the other end, you should use the | chai^nel | 
key to locate to the process followed by the | imfo | key to obtain process details. 



9.15.4 Debugging in the presence of software virtual links 

When the configurer creates software virtual links it places additional processes 
onto the processor in order to provide the virtual link servkies. These processes 
will be displayed by the debugger — it displays all processes it finds on the run 
queue, links etc. A consequence of this is that, occasionaliy, a process will be 
displayed which forms part of the software virtual link system. It Is not possible 
locate to these processes (as they are is not part of the program being debugged). 
These processes may be identified by noting the Iptr and Wdesc values and 
using the [V] command to search for a process with a code area which contains 
the Iptr value, and a stack area which contains the wdesc value. If the name of 
the process is ''%router [ ] " then it is a software virtual link process which you may 
not locate to. 

A similar problem occurs when attempting to locate to a process waiting on a trans- 
puter link which Is used by the software virtual link system — the debugger will 
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complain that it cannot find a file with a name such as Vrdebxx, tco" (where xx 
is a sequence of digits). 

Another problem encountered with using software virtual links and idebug is that 
low priority user processes are promoted, temporarily, to high priority when they 
communicate on software virtual links The debugger cannot tell if they were origi- 
nally at high or at low priority: it will locate to what it believes is a high priority 
process. In general, this is nota problem rf you wish to inspect variables etc. If this 
does present a problem and you know that a particular process is a low priority 
process, you should use the [o] command and specify a low priority wdesc when 

prompted, by setting the least significant bit of the Wdesc value of the process (e.g, 
%1234 becomes %1235). 

In general, the prefened method for locating processes waiting on external 
communications when software virtual links are present is the Monitor page \Y] 
command. If however, you know that a transputer link is not used for software 
virtual routing, you shouid use the Monitor page [T] command to locate to such 
processes. 

9.15.5 Selecting events from specific processors 

The debugger provides no guarantee that debugging events, such as breakpoints 
and debugging messages, from processes running on different processors are 
presented in the same that order they occur in. Events on processors which are 
closer, in terms of connectivity, to the root transputer (where the debugger is 
running) are usually displayed t>efore events on more distant processors. 

If it is important that you encounter a debugging event on a specific processor 
before events on other processors, you can usually achieve this by changing to 
the processor of interest (using the monitor page [p] command or left and right 
cursor keys) before resuming via the [T] or | resume~| command. 

9.15.6 Minimal confidence check 

A first level confidence check to perform with a program which Is misbehaving is 
to perform a 'compare memory' check using the monitor page [C] command. This 
will help to highlight any memory corruption problems which may occur due to 
faulty memory or faulty program logic. If using Occam, you can prevent out of 
range accesses to memory by ensuring that no compiler checks have been 
disabled. 



9.15.7 INTERRUPT key 

The debugger can be diverted fi^om the running program to return to the monitor 
page by the use of the | interrupt "] key. However, problems can arise if the 
running program is simultaneously trying to read from the keyboard; the debugger 
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is then unable to intercept the interrupt key, (Sometimes it is possible to force the 
intenojpt to be recognized by repeating the key quickly) 

A similar problem arises when there are existing keystrokes buffered before the 
interrupt key; if the appik^tion program does not read these buffered keystrokes 
the debugger will never have a chance to see the interrupt key. 



Note: The | INTERRUPT] key will disable all iserver requests to the application 
until the debugger is directed to resume the application. 

9.15.8 Program crashes 

If the debugger detects that the program has crashed immediately after starting 
program execution (i.e. after the Q], Jump Into application, command), you 
should use the post-mortem debug command, [Y], to determine the cause. 
However, if no error flags are set on the network that is running the program then 
it is likely that an em>r flag is set on a transputer that is not in use. This may occur 
on boards where the subsystem services are wired to propagate all error flags to 
the root transputer. In this instance you need to clear all the en^r flags in the 
network (see section 9.7.4). 

9.15.9 Undetected program crashes 

When operating jn breakpoint mode and a program overwrites the debugging 
kernel or you have set a breakpoint in a high priority process on a processor 
without hardware breakpoint support, the debugger cannot fully recover and is 
unable to indicate that the program has crashed. In this situation the debuggerfails 
to update the screen other than to put the following message at the top of the 
screen when it attempts to display the monitor Page: 

Toolset Debugger : V4.00.00 Processor n ''name" (Txxx) 

In such instances you should use the host BREAK key in order to terminate the 
debugger and restart the debugger using the command tine 'M* option to post- 
mortem debug the session, 

9.15.10 Debugger hangs when starting program 

If the debugger hangs immediately after you have supplied the command line 
arguments when starting execution of a program you have probably set a break- 
point in a configuration-level, high priority process on a processor without hard- 
ware breakpoint support. 

9.15.11 Debugger hangs 

If the debugger hangs when attempting to flip to post-mortem mode using the 
monitor page [T] command, or when trying to quit, you should terminate the 
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debugger manually using the host BREAK key. If you were trying to switch to post- 
mortem mode you should restart the debugger using the command line "M' option 
to resume debugging in post-mortem mode. 

9.15.12 Catching concurrent processes with breakpoints 

Sometimes a concurrent process is executing in a program (often in a loop) and 
you would like to be able to control it better by using breakpoints. If the process 
is communicating with other processes via channels, and you have set break- 
points in these other processes, then breakpoints can be set on a communication 
and, when you hit that breakpoint, the channel can be jumped down to debug the 
executing process. 

However, ff the process has entered a non-communicating loop or you are not sure 
where exactly it is in your program coda, you must use a d ifferent approach. In 
order to set a breakpoint, you should use the | interrupt "| key to return to the 
monitor page and then, by using the [r] (Run queues) command and/or the [T] 
(Timer queues) command, list the iptrs and Wdescs of the processes currently 
executing. (Often, this will include the debugging kernel processes but these are 
easy to detect because they are marited as kernel processes.) 

Use the [g] (Goto process) command to select the Iptr and wdesc to locate 
symbolically to the process. You can then set a breakpoin t on that lin e, return to 
the monitor page and resume the program using the |T] Qr | resume"! command; 
when the process hits the breakpoint you may continue to debug it. If there are no 
processes on either the run ortimer queues and there are no external communica- 
tions, it means that your program has either deadlocked or temiinated. 

9.15.13 Phantom breakpoints 

Because of the mechanism used for breakpoints on those transputers without 
hardware breakpoint support (see table 9.2) it Is possible for the output from the 
INMOS compilers to contain code that fools the debugger into thinking it is a break- 
point (a phantom breakpoint). This happens when the code contains an empty 
loop that does not terminate. The following code examples will generate phantom 
breakpoints: 



c 


Occam 


FORTRAN 


while (1) { 
) 


WHILE TRUE 
SKIP 


DO WHILE TRUE 
END DO 


for {;;}{ 

r 
) 




100 GOTO 100 



If you encounter a phantom breakpoint and you wish to continue execution, you 
must set a breakpoint at the same address and then resume execution. To do this 
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use the | GET ADDRESS | key to obtain the start address of the empty loop when in 
symbolic mode, change to the monitor page and use the Set Breakpoint option on 
the Breakpoint menu to set a breakpoint at the loop address. 

9.15.14 Breakpoint conflgunitjon considerations 

When breakpoint debugging you should remember that the root transputer of a 
network is used by the debugger for Its own purposes. On some transputer 
motherboards wth an built-in pipeline, the rooltransputer is normally booted down 
link 0; subsequent transputers in the pipeline boot down link 1 . This may (acciden- 
tally) be a problem If you simply take a network configuration which was not confi- 
gured with breakpoint debugging in mtnd (e.g. a pipeline configuration) and 
attempt to breakpoint debug it. The debugger will in effect, attempt to skip load It 
onto the rest of the network; the program may load (if by chance the right link 
connections are available) but, if the boot link is different, it will not be able to talk 
to the host (via iaerver) when it executes. 

Such a problem may easily be checked for by using the monitor page |T] 
command when positioned on processor 0. This will indicate whether the root 
transputer was booted from a different link to that specified in the configuration file. 

When breakpoint debugging, the debugger will warn you if the boot link is different 
from that expected for ttie root processor before the network Is loaded. 

9.15.15 Determining connectivity and memoty sizes 

In order to establish the connedhrity and memory map range for each processor 
in a program you should use the icollect 'P' option. AJtematively you may use 
the debugger command line option t>' (dummy debug). 

9.15.16 Long source code lines 

Source code lines k)nger than 500 characters cause the symbolic source code 
browser to treat them as multiple lines and subsequently it will loose line synchro- 
nization; (i.e. it displays incorrect line number infcmnation). 

9.15.17 Resuming breakpoints on the transputer seten instruction 

If an attempt is made to resume from a breakpoint whk:h is at the address of a 
seterr Instmction, the debugger does ml continue with the original (correct) Iptr 
(it resumes with an iptr within the kernel area). Because the debugger operates 
in Halt-on-Error mode, the seferr instrucbon wll halt the processor. 

The effect of the incorrect Iptr is only apparent if you subsequently switch to post- 
mortem debugging whereupon the debugger will complain that it is unable to 
locate to an iptir within the kernel area, tf ^is is a problem, you should note the 
Iptr before resuming from the breakpoint 
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Setting and resuming breakpoints on an Occam STOP statement compiled in 
HALT mode, will cause this problem. 

9.15.18 Shifting by large or negative values 

The shift instructions on current transputers take time proportional to the number 
of places shifted — as this number is unsigned, negative values will be b-eated as 
large positive values. Large shifts will cause current transputers to temporarily 
'lock' fora numberof cycles equal to the number of places shifted —on 32 bit b-ans- 
puters this can cause the device to hang-up for up to 2^ cycles (approximately 3V2 
minutes for a 20 MHz device). 

Some languages, such as C, performs no runtime checks for invalid shift values 
and so do not protect you against their consequences. Other languages, such as 
Occam, do perform such checks. 

If the debugger, in post-mortem mode, locates to a source line containing a shift 
operator and the error flag has not been set then It is likely that a shift by a large 
value is taking place — this can be verified by using the | inspect | key to check 
the shift count, 

9.15.19 Aspects of C debugging 

Arrays as arguments to C functions 

Because C requires a declaration of a parameter as array of type to be adjusted 
to pointer to type the debugger must treat all an^ay parameters as pointers. This 
means that it cannot automatically display the contents of an an^y passed as a 
parameter. 

In order to display the contents of arrays you should use specify the range of the 
anciy to be displayed. This is illusb-ated In the following example. 

void foo (int p[4]) { 

debug_stop () ; 
} 

The argument p will be tr eated as a p ointer to int rather than an array of int by 
the C compiler Using the | inspect" | function on p will cause the address of p to 
be displayed. In order to see the contents of the an^y, the inspect command should 
be given an an^ay range, for example: p [0 ;3] . 

Backtracing with concurrent C processes 

idebug supports backtracing from a parallel pnscess to the parent process (where 
the parallel process was started via a C library call). However, for processes 
started asynchronously via ProcRun, ProcRunHigh, or ProcRunLoWj idebug 

merely enables you to backtrace and does not allow operations such as inspection 
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of variables after a backtrace. This is because the parent process which started 
the asynchronous processes may no longer exist, in which case inspection is 
meaningless. 

Errors generated by the full C library 

Generally, the full C runtime library Is able to detect when there is insufficient 
memory for it to function con-ecUy; in such instances it displays an en*or message 
at startup. 

In rare circumstances the library is able to detect that there is insufficient memory 
but it does not have enough memory to display the startup eror message. In such 
instances, it sets the en-or flag and terminates execution. If a program sets the 
en-or flag and the debugger is unable to backtrace when the last instmction 
executed was seterr (error explicitly set), and the following en-or message is 
displayed by the debugger then it is highly likely that insufficient memory is avail- 
able for either the static or the heap area: 

Error: Not compiled with debugging enabled "libc.lib" 

Errors generated by the reduced C library 

Because the reduced C runtime library has no host to communicate with, if a 
mntime error occurs the reason for the emDr is not readily apparent. If a program 
sets the en^orflag and the debugger is unable to backtrace when the last instruction 
executed was seterr (error explicitly set), and the following error message is 
displayed by the debugger then it is highly likely that insufficient memory is avail- 
able for either the static or the heap area: 

Error: Not coo^iled with debugging enabled '^libcred.lib" 

C compiler optimizations 

The INMOS compilers perform some code optimizations. If an extemal variable 
is optimized out from a module because it is never used then the debugger is 
infonned of this and is able to relay the information to the user. 
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However, for some optimizations the debugger Is not informed and consequently 
it may provide misleading infomiab'on. The following code illustrates this: 

int main (void) { 



int 


a = 0; 










int 


b = 0; 










while 


(1) { /* 


or 


'for (; 


;)' 


V 















/* following code optimized out by compiler 

* as it can never be reached 

*/ 
a = 42; 
b = a + 1; 
a = b * b 



} 



in these cases the debugger may show the discrepancy in either of the following 
ways: 

1 If a function follows the optimized code, the debugger associates the 
address of the optimized lines with the address of the start of the function. 

2 If no ftjnction follows the optimized code then the debugger indicates that 
it is unable to find the address for any of the optimized lines. 



9.16 C debugging example 

This example illustrates some of the post-mortem and breakpoint features of the 
debugger. The debugger is njn in interactive mode. 

A similar example program written in Occam is described in section 9,17. 



9.16.1 The example program 

The example program f acs . c calculates the sum of the squares of the first r? 
factorials, using a rather inefficient algorithm. It has been structured this way for 
clarity in process structure and to demonstrate parallel processing and debugging 
methods. The same program coded in Occam is supplied with the occam 2 
toolset. The program incorporates five processes, each coded as a separate func- 
tion. The five processes in turn input n, calculate factorials, square the factorials, 
sum the squares, and output the result. The program is listed below. 
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/*****-kifkic-k***-k****lr'k***1i1t**-ifk* ********* 

* 

* Debugger example: faca.c 

* 

* idebug (and parallal C) «3cai^lo basod on similar program 

* in Occam toolset. 

* 

* Uses 5 procesaes to confute the sura of the squares of the 

* first N factorial* using a rather inefficient algorithm. 

* 

* Plumbing : 

* 

* - > feed -> facs -> square -> sun -> control <-^> User I/O 

* 1 I 



****************** ******lrli**1t*iiit****** * i 



#include <stdio.h> 
linclude <stdlib.b> 
finclude <process.k> 
finclude <channel.h> 



const double stop_real = -1.0; 
const int atop_integer = -1; 

/* output a double down a channel */ 

void 

ChanOutDouble (Channel *out, double value} 

{ 

ChanOut {out, (void*) lvalue, sizeof (value)); 
} 

/* input a double from a channel */ 

double 

ChanlnDouble (Channel *in) 

{ 

double value; 

Chanin (in, (void *) fivalue, isizeof (value)); 
return value; 
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/* coiBpute factorial */ 

doubly 

factorial (int n) 



{ 



double result ; 
int i ; 

result = 1.0; 

for (i = 1; i <= n; ++i) { 
result = result * i; 
} 
return result; 



/* source stream of ints */ 

void 

feed (Process *p, Channel *xxif Channel *out) 



{ 



int n, i; 

(void) p; /* stop compiler usage warning */ 

u = Chanlnint (in) ; 

for (i = 0; i < n; ++i) { 

ChanOutInt (out, i) ; 
} 
ChanOutInt (out, stop integer) ; 



/* generate stream of factorials */ 

void 

facs (Process *pr Channel *in, Channel *out) 



{ 



int x; 

double f ac ; 

(void) p; /* stop compiler usage warning */ 

X = Chanlnint (in) ; 

while (x != stop_integer) { 

fac = factorial (x) ; 

ChanOutDouble (out, fac) ; 

X = Chanlnint (in) ; 
) 
ChanOutDouble (out, stop^real) ; 
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i* generate stream of squares */ 

void 

square (Process *p, Channel *in, Channel *out) 



I 



I 



double X, sq; 

(void) p; /* stop compiler usage warning */ 

X = ChanlnDouble (in) ; 
while (x != stop_real) { 

sq = X * x; 

ChanOutDouble (out^ sq} ; 

X = ChanlnDouble (in) ; 
> 
ChanOutDouble (out, stop_real) ; 



/* sum input */ 

void 

sum (Process *p, Channel *in, Channel *out) 



K 



double total, x; 

(void) p; /* stop con^jiler usage warning */ 

total = 0,0; 

X = ChanlnDouble (in) ; 

while (X != stop_real) { 

total = total + x; 

X = ChzmlnDouble {xsx) ; 
) 
ChanOutDoiJble (out, total) ; 
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/* user interface and control */ 

void 

control (Process *p, Channel *in, Channel *out) 



{ 



double value; 
int n; 

(voidj p; /* atop cowqiiler usage warning */ 

printf C'Sum of the first n squares of factorials\n") 

do { 

printf ("Please type n : ") ; 
} while (scanf (''%d", &n) != 1); 
printf {"n - %d\xi" , n) ; 
printf {'Calculating factorials ... '') ; 

ChanOutInt (out, n) ; 
value = ChanlnDouble (in) ; 

printf ("XnThe result was : %g\n"j value) ; 



Channel * 
CheGlced_ChanAIloc {) 

i 

Channel *chan; 



if ({chan = ChanAlloc ()) = NUUi) { 

fprintf (stderr, "ChanAlloc () failed\n") ; 
exit (EXIT_FAILURE} ; 

) 

retiorn chan; 



Process * 

Chec)ced_ProcAlloc (void (*func) () , int sp, int nparam, 
Channel *cl, Channel *c2} 



{ 



Process *proc; 

proc = ProcAlloc (func, sp, nparam, cl, c2} ; 
if (proc ^ NOLL) ( 

fprintf (stderr^ "ProcAlloc () failed\n") ; 

exit (EXIT_FAILOFE) ; 
\ 
return proc; 
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int 

main (void) 



Channal *facs_to_sqQara, *squara_to_suitt; 
Channol *sum_to_cont.rol , *food_to_f acs ; 
Cha^Mial *control_to_faod; 

Process *p_feed, *p_facsr *p_square; 
Process *p sum^ *p control; 



facs_to_&quare = Chec)ced_CharUU.loc { 

squar«_to_sum = Checkod_ChaiiAlloc { 

s\mL_to_control = Checked_ChanAlloc ( 

fQed_to_facs = Checked_ChanAlloc ( 

control to feed = Checked ChanAlloc ( 



p_feed = Chacked_ProcAlloc (feed, 0, 2, 

control_to_feed, faed_to^facs) ; 
P_facs = Ch«cked_ProcAlloc (facs, 0, 2, 

f aad_t:o_f acs / facs_to_square) ; 
p_square = Checked_ProcAlloc (squara, 0, 2, 

f aca_to_squaro ^ sqaare_to_sum) ; 
p_sum = Chacked_ProcAlloc {sxaa, , 2, 

5quara_to_«um, stim_to_control) ; 
P_control = Checkftd_ProcAlloc {control, 0, 2, 

sum_to_control , control_to_f eed) ; 

ProcPar (p__faed, p_fac«, p_square, p_sum, 

p_controlr NULL); 

exit (EXIT_SUCCESS) ; 



9.16.2 Compiling and foading the example 

The source of the program is provided in the toolset debugger examples subdi- 
rectory. It should be compiled for transputer class TA with debugging enabled, then 
linked with the appropriate library files and made bootable using icollect with 
the 'T' option to create single transputer bootable code. 
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Figure 9.4 Hardware configuration for the example 
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The example is intended for running on a BOOS board wired subs. See section 4.7 
in tiie accompanying Toolset Reference Manual debugger chapter if your system 
is different. 

A typical sequence of commands for compiling^ linking, and booting the program 
is shown below. The 'I' option on the linker command line is optional but provides 
useful information on the progress of the linking operation. 

Command sequences are shown for UNIX-based and MS-DOSA/MS-based tool- 
sets. Use the appropriate set of commands for your system. 

UNIX: 

ice faes.c -g ^ta -o facs.tax 

ilink facs,tax -f cnonconf.lnk -ta -o facs.cah -i 

icollect facs.cah -t 

MS-DOSA/MS: 

ice faes.c /g /ta /o facs.tax 

ilink facs.tax /f cnonconf.lnk /ta /o facs.cah /i 

icollect facs.cah /t 

The program is loaded for breakpoint debugging by running idebug with in inter- 
active mode using one of the following commands: 

idebug -sr -si -b2 facs.btl -c t425 

idebug /sr /si /b2 facs.btl /c t425 

This command starts up the debugger and displays the Monitor page but does not 
start the program. The iserver 'si' switch is optional. 

Note: If your transputer is not a T425 you should change the t425 option to the 
appropriate transputer type. You may also need to change the number specified 
after the 'B' option to the number of the root transputer link to which the network 
is connected. See table 44 in chapter4 of the accompanying Toolset Reference 
Manuanor more details about the options to use, if in doubt. 



9.16.3 Setting initial breakpoints 

Initial breakpoints can often be set by using the Monitor page [T] command and 
specifying a breakpoint at the start of main { ) . in this example we use a different 
method based on setting specific breakpoints in the source code before the 
program is started. 

At the Monitor page select [T] to display the source file. At the object module file- 
name prompt specify the compiled object file facs.tax. The debugger uses 
debug information within the object module to select the source file. 
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The source file is displayed with the cursor positioned at the first function definition. 
At this point the program is still waiting to be started. 

Set a breakpoint at the beginning of the ChanOutDouble ( ) function 
using [ TOGGLE BREAK] , The debugger confirms the breakpoint is set and gives 
the breakpoint a unique fdentification number (note that the breakpoint is set on 
the first executable line of the function). 

9.16.4 Starting the program 

Retum to the Monitor page using the | MONITOR | key and start the program by 
selecting the[T] command Press | return | at the 'Ccaamand lin«' prompt {no 
command line Is required) and give a small positive number (e.g. 12) when the 
program prompts for input. The program runs until it reaches the breakpoint 

9.16.5 Entering the debugger 

At the breakpoint the debugger displays the number of the breakpoint and the 
number of times it has been encountered (or hit) and then requests confirmation 
to continue tfie stopped process. Press any key except [r] or [T] to enter the 
symbolic debugging environment. The debugger locates to the breakpoint and 
displays the source code. 

9.16.6 Inspecting variables 

Variables and channels in ChguiOutPouble Q can now be examined. For 
example, to examine the variable value press ("inspect | and specify its name 
at the pr ompt. The d ebugger displays the value 1.0 and labels it as a double. 
Pressing | INSPECT | with the cursor positioned on value has the same effect. 

Note that only variables in scope at the debugger's cun^ent location point can be 
inspected, although the rest of the file can be displayed with the cursor keys. The 
current location point is at the start of function ChanOutDouble () . 

9.16.7 Finding addresses of variables 

The debugger provides a comprehensive C expression language which may be 
used with INSPECTand MODIFY. To obtain the address of a variable , you use the 
same expression as you would in a C program. Press | inspect] and specify 
&value to display the address of value. Notice that addresses are displayed in 
hex notation by default. |~tOGGLEHE^ may be used to display the values of vari- 
ables in hex notation if required. 

9.16.8 Backtracing 

ChanOutDouble () is called from function facs () to output the factorial Itcafcu- 



lates for each integer received from f eed () , To confirm this press | BACKTRACE^ 
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and the debugger locates to the line in £acs() where ChanOutBoubleO is 
called. Press | TOP | to return to where the breakpoint occurred. Now press 



I TOGGLE BREAK | to remove the breakpoint on this line. 

9.16.9 Jumping down a channel 

Within f acs ( ) the variable f ac is the first in a sequence of outputs on the channel 
out. To trace the destination process for f ac first use | inspect j to see the value 
of the channel out, which is declared to be a channel pointer. Use | inspect j 
again but this time specify *out, which de-references the channel pointer The 
debugger displays an iptr and wdesc, indicating that there is a low priority 
process waiting at the other end of the channel. 

Now press | channel] and again specify *out to de-reference the channel 
pointer The debugger jumps down the channel connecting the two processes and 
locates to ChanInDouble{). Now backtrace to the function which called 
ChanlnDoubleO to inputa value^ namely function square () . Variables in scope 
now become available for inspection (at this stage they have not been initialized). 

While stili in function square () move the cursor t o the first l ine containing 
ChanOutDouble C ) and Set a breakpoint Then press | RESUME^ in order to run 
the program up to the breakpoint just set. 

9.16.10 Inspecting by expression 

I n function square inspect the variable sq and check the computation by 
I inspect I and specifying the expression x * x. Note how | inspect | can be 
used to perform arithmetic on any variable in scope. Expressions can also include 
numbers and other variables and constants in scope at the location point. 

Press I inspect I and type x ?= stop_real in order to see the value used to 
control the while loop. 

9.16.11 Modifying a variabte 

In breakpoint debugging any program variable may be modified. To modify a vari- 
able X press I MODIFY I and specify x at the 'Destination' prompt. The debugger 
now requests the new value by display the 'Source' prompt. Enter any value and 
check the value has changed by inspecting x once again. 

9.16.12 BacktracingtomainO 

While still in square ( ) , press | BACKTRACE | to locate back to where the function 
was called. The debugger locates to ProcPar ( ) in function main ( ) where the 
five major processes are started in parallel. If the call to function square ( ) had 
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been nested in other calfs, successive | backtracFI operations might have been 
necessary but would have eventually located to the call in the program main func- 
tion. 



9.16.13 Entering #include files 

Press I GOTO LINE | and select line 20, This will locate you to the line 
iinclude <stdio . h>. By using the | EhtTERFlLE] key you may now enter the 
#include file (and then any nested files within it); the | exit file ] key will bring 
you out again into the enclosing file. 

9.16.14 Quitting the debugger 

Finally, to quit the debugger use the | FINISH [ key (you may also quit the debugger 
from the Monitor page using the[Q] command). If the debugger was run with the 
'XQ' option, then it will prompt for confirmation before exiting. 



9.17 Occam debugging example 

This example illustrates some of the post-mortem and breakpoint features of the 
debugger. The debugger is mn in interactive mode. 



9.17.1 The example program 

The example program f acs , occ calculates the sum of the squares of the first n 
factorials, using a rather inefficient algorithm. It has been structured this way for 
clarity in process structure and to demonstrate pamllel processing and debugging 
methods. The same program coded in C is supplied with the C toolset. The 
program incorporates five processes, each coded as a separate procedure. The 
five processes in turn input n, calculate factoriaEs, square the factorials, sum the 
squares, and output the result. The program is listed below. 

Note: Triple braces({ { { and }} ))in the listing indicate fo/cf marks in thepn^gram. 
They are retained for compatibility with the folding editors often used for writing 
Occam programs. 

The source file can be found in exanples/manuals/idebug. 
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— Debugger exan^le : f acs , occ 

— Uses 5 processes to confute the sum of the squares 

— of the first K factorials using a rather inefficient 

— algorithm . 

— PlTBnbing : 

— fQed-> facs^> squars-> sum-> control < — > Dser 10 

I I 



#INCLDDE "hostio.inc" 
#aSE "hostio.lib" 

PROC f acs. entry (CHAN OF SP fs, ts, []INT free. memory) 

VAL stop. real IS -1.0 (EEAL64) : 
VAL stop, integer IS -1 : 

— {{{ FDNC factorial - compute factorial 
REAL 64 FtJNCTION factorial (VAL INT n) 
REAL64 result : 
VALOF 
SEQ 

result := 1.0 (REAL64) 
SEQ i = 1 FOR n 

result := result * (REALe4 ROUND i) 
RESULT result 

— }}) 

— {{{ PROC feed - source stream of integers 
PROC feed (CHAN OF INT in, out) 
INT n : 
SEQ 
in ? n 
SEQ i = FOR n 

out \ i 
out ! stop . integer 

— }}} 
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— {{{ FROC facs - gdndr«t« stream of factorials 
PROC facs {CHflN OF INT in, CHAN OF BEAL64 out) 
INT X : 
REAL64 fac : 
5EQ 
In ? X 

HHILE X <> stop.i&t«g«r 
5EQ 

fac := factorial (x) 
out ! fac 
in ? X 
out ! stop. real 

— {[{ PROC square - generate stream of squares 
FROC square (CHAN OF REAI.64 in, out) 
REAL64 X, sq : 
SEQ 
in ? X 

WHILE X <> stop. real 
SEQ 

sq := X * X 
out ! sq 
in ? X 
out 1 stop . real 

— }}} 

— {{{ PROC sum - sum input 

PI^X: sum (CHAN OF REAL64 in, out) 
REALe4 total, x : 
SEQ 

total := 0,0 (BEAL64) 
in ? X 

HHILE X <> stop. real 
SEQ 

total := total + x 
in ? X 
out ! total 

— })} 
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— { { { PROC control - us«r interface and control 
PROC control (CHAN OF SP fs, ts, 

CHAN OF BEAL64 result. in, 
CHAN OF INT n.out) 
REAL 6 4 value : 
INT n : 
BOOL error : 
SEQ 

so . write . string . nl { f s , ta , 

Sum of the first n squares of factorials") 

error :- TRUE 

KHILE error 
SEQ 

so . write . string (ts, ts, "Please type n: ") 
so. read. echo. int {fs, ts, n, error) 
so . wri te.nl ( f s , t s ) 

so.write.string(fs, ts, "Calculatiing factorials. . .") 

n.out ? n 
resTilt.in ? value 

so, write.nl {fs, ts) 

so. write -string (fs, ts, "The result was: ") 

so,write.real64 (fs, ts, value, 0, 0) — free format 

so.write.nl (fs, ts) 

so. exit (fs, tS/ sps. success) 

— })) 

CHAN OF REALe4 f acs . to . square , square . to . sum : 

CHAN OF REAL 64 sum. to. control : 

CHAN OF INT food. to. facs, control . to . feed : 

PAR 

feed (control. to. feed, feed. to. facs) 

facs (feed. to . facs , facs . to . square) 

square (facs. to. square, square . to . sum) 

s\mL ( square . to . sum, sum. to . control) 

control (fs, ts, sum , to . control , control . to . feed) 



9.17.2 Compiling the facs program 

The source of the program is provided in the toolset examples subdirectory. It 
should be compiled for transputer class TA with debugging enabled, then linked 
with the appropriate library files and made bootable usmg icollect with the 'T' 
option to create single transputer bootable code. The example is intended for 
running on a BOOS board wired subs. See section 4.7 in the accompanying Toolset 
Reference Manual debugger chapter if your system is different. 
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Using imakef 

[f yoursystem has a make utility you may use imakef to generate a suitable make- 
file to help build the program: 



imakef facs.bah 



make 
mstke 



-f facs.mak 
/£ facs.mak 



(UNIX) 
(MS-DOS/VMS) 



Using tlie tools directly 

A typical sequence of commands for compiling, linking, and booting the program 
is shown below. The 'I' option on the linker command line is optional but does 
provide useful information on the progress of the linking operation. 

Command sequences follow for UNIX-based and MS-DOSA/'MS-based toolsets. 
Use the appropriate set of commands for your system. 

UNIX: 

oc -ta facs.occ -o facs.tah 

ilink -ta facs.tah hostio.lib convert. lib -f occama.lnfc 

-o facs.cah 
icollect -t facs.cah -o facs.bah 

MS-DOS/VMS: 

oc /ta facs.occ /o facs.tah 

ilink /ta facs.tah hostio.lib convert. lib /£ occama.lnk 

/o f acs . cah 
icollect /t facs.cah /o facs.bah 

9.18 Breakpoint debugging 

The following section demonstrates how to debug the example program in interac- 
tive mode. 
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Figure 9.5 Hardware configuration for breakpoint example 

9.18.1 Loading the program 

The program is loaded for breakpoint debugging by running idebug in interactive 
mode using one of the commands given below. Use the appropriate command for 
your system. 

idebug -sr -si -b2 facs.bah -c t425 (UNIX) 

idebu? /sr /si /b2 facs.bah /c t425 (MS-DOS/VMS) 
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This command starts up the debugger and displays tiie Monitor page but does not 
start the program. The iserver 'SI^ switch is optionai. 

Note: If your transputer is not a T425 you should change the t425 option to the 
appropriate transputer type. You may also need to change the number specified 
after the 'B' option to the number of the root transputer fink where your network is 
connected. See table 4.4 in chapter 4 of the accompanying Toolset Reference 
Manual for more details about the options to use if in doubt. 

9.18.2 Setting initial breaicpoints 

Initial breaicpoints can often be set with the Monitor page [b] command and speci- 
fying an entry point breakpoint (this would set a breakpoint at f acs . entry). In this 
example a difTerent method is used based on setting specific breakpoints in the 
source code before the program is started. 

At the Monitor page select option [T] to display the source file. At the object 
module filename prompt specify the compiled object file f aca . tah. The debugger 
uses debug information within the object module to select the source file. The 
source file f acs . occ is displayed with the cursor positioned at the first procedu re 
definition, namely facs. entry. At this point the program is still waiting to be 
started. 

Use I GOTO L INE I to move the cu rsor to line 56 (out t fac) and set a break- 
point there using | toggle BREajTI . The debugger confirms the breakpoint Is set 
and gives the breakpoint a unique identification number. 

9.18.3 Starting the program 

Return to the Monitor page using the | monitor ) key and start the program by 
selecting thejT] command. Press [return] at the 'Command line' prompt (no 
command Jine is required) and give a small positive number (e.g. 12) when the 
program prompts for input. The program runs until It reaches the breakpoint. 

9.18.4 Entering the debugger 

At the breakpoint the debugger displays the number of the breakpoint and the 
number of times it has been encountered (or hit) and then requests confirmation 
to continue the stopped process. Press any key except [R] or [T] to enter the 
symbolic debugging environment. The debugger locates to the breakpoint and 
displays the source code. 

9.15.5 Inspecting variables 

Variables and channels in facs can now be examine d. For exam ple, to examine 
the variable f ac move the cursor to f ac and press | inspect | . The debugger 
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displays the value as REAL64 l , and gives its address. Pressing | enspect | 
with the cursor positioned on a space causes the debugger to prompt you for a 
symbol. Note that only variables in scope at the debugger's current location point 
can be inspected, although the rest of the file can be displayed with the cursor 
keys. The current location point is line 56 in the procedure facs. 

9.13.6 Backtracing 

f ac3 is called in parallel by f acs , entry to output the f actorial it calcu lates for 
each integer received from feed. To confinn this press | backtracTI and the 
debugger locates to the line in f acs . entry where facs is called. Press | TOP | 
to return to where the breakpoint occun-ed. The cun-ent location point is line 56 in 
the procedure faca. 

9.18.7 Jumping down a channel 

Within facs the variable f ac is the first in a sequ ence of ou tputs on the channel 
out. To trace the destination process for f ae first rfNSPECT | the channel out. The 
debugger displays an Iptr and Wdese, indicating that there is a low priority 
process waiting at the other end of the channel. 

Now press [ channel | and again specify out. The debugger jumps down the 
channel connecting the two processes and locates to the corresponding channel 
Input in procedure square {the statement in ? x). Variables in scope within 
square now become available for inspection (at this stage they have not been 
Initialized). 

9.18.8 Modifying a variable 

In breakpoint debugging program variables may be modified. Start by first 
inspecting x in order to ensure that the ne w value wil l be different. To modify the 
variab le x position the cursor on x and press | modify | . At the modify value prompt 
specify the value to be placed in x. Note that the modify prompt reminds you of the 
type of X. Enter any valid value and check the value has changed by inspecting 
X once again. 

9.18.9 Entering #INCLUDE files 

Press I gotoline"! and select line 17. This will locate you to the line 
#INCLUDE "hostio , inc". By using the | ENTER F(LE"| key you may now enter 
the #INCLUDE file (and any nested fINCLUDE files within it); the | EXIT FilE j key 
will bring you out again into the enclosing file. 

9.18.10 Resuming the program 

To resume execution of the program from the current breakpoint press 
the I RESUI^E I key. This will cause the program to continue running until it encoun- 
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ters the breakpoint again. Press an appropriate key to enter the symbolic debug- 
ging environment. This wNI cause the debugger to locate to line 56. 



9.18.11 Clearing a breakpoint 

To clear the breakpoint already set at line 56 use the | toggle BREAi<"] key. The 
debugger will confirm that the breakpoint has been cleared. Press 1 RESUME | to 
resume execution and cause the program to display its result. The debugger will 
confjnn that the program has finished and will pause in order to enable you to read 
the output from the program. Press any key as indicated to enter the Monitor page. 
Note that the Monitor page displays the exit status from the program. 

9.18.12 Quitting the debugger 

Finally, to quit the debugger you can use the Monitor page [Q] command. You may 
also quit the debugger from symbolic mode by using the | FINISH | key. If the 
debugger was run with the 'XQ' option, then it will prompt for confimiatlon before 
exiting. 



9.19 Post-mortem debugging 

The following section demonstrates how to debug the example facs program In 
post-mortem mode. 















HOST 




T425 

root 

transputer 

















Figure 9.6 HanJware configuration for post-mortem example 

9.19.1 Running the example program 

When you have built an executable code file you can run the program by typing 
one of the following commands: 



iserver -se -sb facs. bah 
iserver /se /sb facs. bah 



(UNIX) 
(MS-DOSA/MS) 



The program immediately prompts you for a value. For con^ect execution the 
number must be less than 100. To create an error for the purpose of this exampie, 
enter the value 101 and press [RETURN]. The program will fail with the message: 
Error - iserver - Error flag raised by transputer. 
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9.19.2 Creating a memory dump file 

To create a memory dump file for the debugger to read, type: 

idump fac5 15000 

This creates a file called facs .dnp containing the transputer's register contents 
and the first 1 5000 bytes of memory. You are then returned to the operating system 
prompt. 

9.19.3 Running the debugger 

To debug the example pnsgramj use one of the following commands: 

idebug -si facs.bah -r fac< -c t425 (UNIX) 

idebug /si facs.bah /r facs /c t425 (MS-DOSA/MS) 

The iserver 'SI' switch is optional. The 'R' option identifies the program as one 
that was executed on the root transputer and specifies the memory dump file to 
be read. 

Note: If your transputer is not a T425 you should change the t425 option to the 
appropriate transputer type. 

Shouid you wish to mn the debugger a second time on this single processor 
example, without an intervening idump command, you will need to add the 
iserver 'SR' Option to the command line to reset the networ1(. 

The debugger first displays its version number, then some processing information, 
and eventually locates to the source line from which the error was generated: 

sq := X * X 

You can now begin to debug the program. You can use the symbolic faciliUes to 
browse the source, locate to specific lines and areas of code, inspect variables and 
channels, and trace procedure calls, and you can inspect and disassemble 
memory using the Monitor page commands. 

The following sections illustrate some of the debugging operations you can 
perform on the example program. For further details about any of the debugging 
functions described in these sections, see chapter4of the accompanying Toolset 
Reference Manual. 

Inspecting variables 

When the debugger is displaying source code, you may inspect any variable by 
placing the cursor on the variable and pressing | IMSPECT | . 

For example, to display the value of x, place the cursor over x in the source code 
and press ! INSPECT | . x is displayed in both decimal and hexadecimal forms, and 
its address in memory is given in hexadecimal. For example: 

REAL64 'X' has value . . . 

9.3326215443944096E+15S (#605166Ce98CF1838) (at #80000464) 
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In the same way you can inspect the values of sq, square, stop, integer, 
stop . real, and any other variable or constant that is in scope. Use the cursor 
keys to scrol l through the code. To return to the source of the original en-or, use the 
I RELOCATE ] function. You can also use the | INSPECT | function to examine proce- 
dures andfunctions. If you place the cursor on a procedure or function name and 
press I INSPECT I , the debugger displays its address and workspace requirements. 
You can also examine any symbol in the s ouree by sp ecifying its name. To do this, 
move the cursor to a blank area and press | inspect ] . The debugger then prompts 
for the symbol name. 

Inspecting channels 

The debugger can also examine processes on channels within the scope of the 
original error If you place the cursor on channel out and press | INSPECT | , 
Information about the channel is displayed. For example: 

CHAN ^OTife' has Iptr:#800022Fe and Wdeac: #80000381 (Lo) {at #S0000G3C) 

This Indicates that there is a process waiting for communication on channel out, 
and t hat it is a low priority process. To find out which Occam process is waiting, 
press I channel] . The cursor will be piaced on the line corresponding to the other 
process, which in this example is inside the procedure sum, on the following line: 

in ? X 

Within procedure sum, you can examine any symbol using | inspect | . Within the 
sum procedure you can inspect the channel out and use [CHANNEL] to jump to 
the waiting process, whic h is the pro cedure control that is waiting for the final 
result Again you can use | inspect] to examine any symbol. 

Retracing and Backtracing 

So far the debugger has located three of the fi ve processe s that compose the 
program. What about the others? First use the | retrace | key to retrace your 
steps back to procedure square. When in procedure square, inspect channel 
in, which is connected to the f acs procedure. It is empty, which means that no 
process is wailing to communicate. 

^^^ ^ I backtraceH . This function backtraces down nested procedure calls. 
Each time the function is used the debugger locates to the line in the enclosing 
code from which the procedure was called. 

In this example, | backtrace^ moves the cursor to the tine where procedure 
square is called. Again, you can inspect any symbol which is in scope at this line. 
For example, you can inspect the channels feed. to. facs and 
facs. to, square. Both should be empty, which means that the remaining 
processes were actively executing, rather than waiting to communicate, when the 
program halted. 
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To find the active processes, you need to examine the transputer's pnDcess 
queues using the Monitor page fadlities, as described below. 

Displaying process queues 

To display the process queues, first e nter the debugger Monitor page from the 
symbolic environment by pressing the | MONiTOR] key Low level information is 
displayed for the current processor, along with a list of Monitor page commands. 

To display the process queues, use the Monitor page [R] command. This displays 
two active processes, identified by their respective Iptr and wdesc. When you 
have Identified the processes to examine, you can use the Monitor page \~G] 
command to jump to those processes and inspect the code. Other commands to 
try from the Monitor page are [T], which displays the processes waiting on the 
transputer's timers; and [T] , which displays processes waiting for communication 
on the transputer's links. 

Goto process 

When you press [g], the following message is displayed: 

Goto process - U8« [CURSOR] then [RETDRH] , or to T, {I)ptr, (L}o or 
{0)uit 

To display the first adive process^ , type [T] (zero). The cursor vwll be placed on 
the following source line (in procedure 'feed'): 

out ! i 

Because this process is on the queue and not waiting, it must have already 
performed the communication and is about to resume executing. You can examine 
variables within the procedure as before. 



To display the last remaining process in the program, press | monitor | again, and 
type [G] followed by [T] to locate to the second process in the queue. This 
process will either be executing code within the compiler libraries or within the 
repEicated SEQ. If it is executing code within a library, the debuggerdisplays the call 
to the library routine rather than the source itself, because the source is not 
supplied. For example: 

result := result * (REAL64 ROtniD i) 

Again, you may inspect variables within the process. For example, by inspecting 
the variable 'i', you can determine how many times the loop has been executed. 
Or you can use rBACKTRACl"] to determine where the function was called from. 

1 . For a full explanation of the possible responses see the definition of the Goto Process command 

in the idebug reference chapter {chapter 4 of tte accompanying Toolset Reference Manuaf). 
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This chapter describes how to use the advanced features of the configurer. It is 
aimed at users who wish to override certain configuration defaults. The chapter 
deals with two topics: 

• Memory usage by the configurer (code placement) 

• Channel communications (channef placement and routing). 

These allow the user to override the default allocation of user's code and data in 
memory, and to refine the channel communication for the target network using 
advanced virtual routing techniques. An example configuration using virtual 
routing \s provided at the end of the chapter 

10.1 Code and data placement 

The configuration language recognizes seven processor attributes {'reserved', 
three 'location' attributes, and three 'order' attributes), which influence the use 
of memory. These are described, with examples, in sections 6.5.5 to 6.5.7. This 
section describes the circumstances In which these attributes should be used. 

'location' and 'order' attributes are nomnally disabled and must be explicitly 
enabled by the configurer 'RE' option. Note: When these attributes are enabled, 
debugging using the toolset debugger idebug is not supported. 

10,1.1 Default memory map 

By default, code is mapped into memory in the following order beginning at LoadS- 
tart: workspace; code; vector space. The memory segments are contiguous. The 
upper limit of the memory available to the configurer Is defined by the memsize 
attribute specified for the processor nodes. 

By default, the configurer onfy knows about this continuous block of memory, 
whose upper and lower limits are set by the value of memsize minus the LoadS- 
tart offset for the processor. The default memory map is iHustrated in Figure 10.1 . 
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memsxze 



Free Space 



Minint = 
MOSTNEG INT 



Program 
Vectorspace 



Program 
Code 



Program 
Workspace 



Reserved by 
transputer 
architecture 



FreeStart 



Contiguous 
memory 



LoadStart 
MemStart 



Figure 10.1 occonf default memory map 

The first 2 or 4Kbytes of memory above MOSTNEG IHT is implemented as on-chip 
RAM, and includes a few words which are reserved by the transputer hardware 
for the implementation of links and other hardware registers. LoadStart is either 
just above or coinddent with MemStart. 



10.1.2 Other memory configurations 

Figure 10.2 illustrates a memory configuration with additional requirements to 
those provided by the configurer in default mode. To cater for such situations the 
reserved and location.... attributes are supported by the configuration 
language. 

Figure 10.2 illustrates two different sets of possible requirements: 

• The first is where the available memory is discontinuous and the lowest 
block of memory is not sufficiently large enough to hold all the code and 
data. 

• The second is where a block of memory is available outside the defauft 
range of memory addressed by the configurer (see above). 
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M05TNEG INT 




location 
MemStart 



Figure 10.2 Example discontinuous memory map 



10.1.3 reserved attribute 

This attribute is used to specify the size of memory, in bytes^ to reserve from 
MOSTNEG IKT which cannot be used by the configurer to place user and system 
processes. The programmer may then use this reserved block in any way, for 
example, to place code and data segments of specific user processes into 
reserved memory using the location. ... attributes. For example, in Figure 10.2 
the reserved attribute has been used to force the configurer to place system and 
user code into the second block of memory and to ignore the on-chip RAM. 

Checks are performed to ensure that the reserved memory size is greater than 
the default LoadStart otfset for the processor and less than the memory size 
specified by the memsize attribute. The configurer will also ensure that the size 
is word aligned by rounding the size up to the nearest word boundary. Note: the 
value of the default LoadStart is variable. 

When the reserved attribute is used, the region of memory available to the confi- 
gurer for automatically placing the non-addressed code and data segments of 
system and user processes is defined as being: 

the top of memory as specified by the memsize attribute minus the 
memory size specified by the reserved attribute. 
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If no reserved attribute is defined then the region of memory available to the 
configurer is: 

the top of memory as specified by the memsize attribute minus the default 
Loadstar! offset for the processor 

The reserved attribute is set within the configuration file MAPPING section using 
a physical processor name. 



Example: 



M21PPING 
DO 

SET processomame (reserved := 5*1024) 



10.1.4 location attributes 

There are three attributes which allow absolute addresses to be optionally speci- 
fied for the code and data segments of a process: location . ws; location . vs; 
and location. code, corresponding to Occam workspace, vectorspace, and 
program code respectively. As an example, Figure 10.2 indicates how the location 
attributes can be used to access memory below LoadStart (which has been 
changed from its default value by the reserved attributes) or spare memory loca- 
tions available on external RAM. 

Note: location.... attributes ovenide the equivalent order.... attributes if 
specified. 

Checks are performed to ensure that any code and data segments that have been 
absolutely addressed using the location.... attributes are not placed into an 
illegal region of memory, such as: 

• memory used by the configurer for automatically placing code and data 
segments i^e. the region defined by Loadstart and the memsize attribute. 
(See section 2.12,1 in the Occam 2 Toolset Reference Manual). 

• address locations that exceed the highest possible memory address loca- 
tion for the processor. 

The configurer will fail with an error message If either of the above occur. An en-or 
will also be generated if the addresses specified are not wonJ aligned. 

A further check is made that the add resses are non-overiappi ng and a warning will 
be generated rf they are. It is not illegal to have overiapping regions of memory 
within the permitted regions for configuration code, as described above. However, 
it is the programmer's responsibility to ensure there is no conflict in the use of over- 
lapping regions at runtime. 

A warning will also be generated if the location . ... attributes place code or data 
at address locations that exist below MemStart. 
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If the location. ... attributes are not specified then the configurer will automati- 
cally place non-addressed code and data segments. 

The location.... attributes are set on a physical processor name within the 
configuration file MT^PING section. 

Example (on a 32-bit processor): 

MAPPING 
DO 

SET processomame (location, code := #80000100) 



This example specifies the start address forthe process code segment. It assumes 
that LoadStart has been redefined, using the reserved attribute. 

10.1.5 order attributes 

The three order attributes described in section 6.5.5, can be used in conjunction 
with the reserved and location.... attributes. The order.... attributes are 
used to change the ordering priority of those process segments automatically 
placed by the configurer i.e. non-addressed code and data segments. They only 
operate within the memory region delimited by LoadStart and the value of the 
memsize attribute. 



10,1,6 location versus order attributes 

location. code, location. ws and location. vs attributes acton the same 
parameters as order . code, order .ws and order .vs, namely, program code, 
workspace and vectorspace. 

As stated in section 10.1.4, if both the location.. ..and order attributes are 
specified for a particular segment, e.g. vectorspace, then the location.... 
attribute will override the effect of the order. ... attribute. 



10.2 Channel communication - configuration techniques 

When software virtual routing is required, the configurer worics by adding multi- 
plexing and demultiplexing processes to implement a number of virtual channels 
over a single hardware link. It will also add routing processes to through-route data 
between processors which are not directly connected. In doing so it assumes by 
default that: 

■ any link to link connections in ttie target networit can be used for imple- 
menting virtual channel traffic. 

• any of the processors can be used for through-routing. 
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• where multiple routes of the same length exist between two processors, 
the virtual channels between these processors should be shared out 
between these routes as much as possible. 

While these are, in general, reasonable assumptions, users may require more 
control over how processors and links are used for implementing virtual channels 
In specific networks. The configurer pemiits users to control its routing decisions 
by means of processor attributes and channel placements which can be defined 
in the configuration source file. These are designed to supply the following capabil- 
ities: 

• A channel may be placed on a specific hardware arc between processors. 
This instructs the configurer to implement the channel directly using the 
hardware link rather than as a \drtuai channel. Only two channels may be 
placed (one in each direction) on a hardware link. This can be used to 
ensure that a limited number of critical channels are directly implemented 
by hardware links. Note: that this placement is ignored if both interactive 
debugging (with idebug) and virtual routing are enabled. 

• It is possible to prevent specific processors from being used as pathways 
for virtual channels required by other processors. This ensures that certain 
critical processors within the target system are not used for through-routing 
virtual channels for less criticai processors. 

• It is possible to ensure that all virtual channels are routed via a group of 
processors specificaliy placed in the target networic to support them. 
Hence a group of smail inexpensive processors may be placed in the 
middle of a network of processors to provide the communications require- 
ments at little cost to the other processors. 

• It is possible to control the number of virtual channel support processes 
that are added to particular processors, and also whether they are given 
use of internal memory fn preference to application processes. This 
preserves the performance of critical processors in the target network and 
allows virtual channel support on processors with limited memory capacity. 

The following sections describe the use of the place statement and the order .... 
attributes to optimize important channels and to make the best use of fast memory. 
Section 10.2.4 introduces the additional attributes used to control the configurer's 
routing system and describes how to use them to meet the requirements identified 
above. An example is described in section 10.3. 

10.2.1 Routing and placement constants 

The include file occonf . inc contains a number of constants associated with the 
routing and placement attributes. The file should be referenced at the top of the 
configuration before the hardware description if any of the configuration constants 
mentioned in the following sections are used, e.g. 

#INCLUDE occonf. inc 
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10.2.2 Optimizing important application channels 

By placing an application channef on a hardware arc rt is possible to reserve the 
hardware I ink solely for the use of the application channel concerned (except when 
interactive debugging with idebug and virtual routing are both enabled). 

With this technique a sub-set of the channels used by an application can be placed 
on a sub-set of the hardware links available within the target system. This then opti- 
mizes the performance of the placed data paths. 

When doing the placement the user must be careful to leave at least enough free 
links to form a minimal spanning tree between each sub-set of processors in the 
target network that require through-routed virtual channels to connect them. (See 
section 10.2.4). 

10.2.3 Virtual communications - use of fast memory 

Normally the workspace segment of virtual channel support processes (added to 
the target network by the configurer), where used, is allocated within fast memory 
(i.e. at the most negative addresses) before the user process code and data 
segments are allocated. 

User process code and data segments can, however, be allocated from intemal 
store before the stack of the virtual channel support processes is allocated. This 
is done by setting order attributes for the relevant user processes to lower values 
than those automatically given to the stack segments of the virtual channel support 
processes- 
Virtual channel support processes are divided into routing processes and multi- 
plexing/demultiplexing processes. Workspace segments of all routing processes 
placed by the configurer are all given the value router, order. Workspace 
segments of all multiplexing/demultiplexing processes placed by the configurer 
are given the valueMDXER. ORDER- Defeult values of -20000 and -10000 respec- 
tively are defined for these constants in the include file occonf .inc which is 
supplied with the toolset. 

So, if order values on the code and data segments of user processes are less 
than ROUTER. ORDER the segments CO ncemed will be allocated from interna! store 
before any of the virtual channel support processes' workspace is allocated. 

If order values on user processes are less than MOXER. ORDER but greater than 
ROUTER . ORDER, only the workspace required by routing processes will be allo- 
cated before the configurer allocates space for the user processes concemed. 

Caution: If the stack segments of heavily-used virtual channel support processes 
are pushed out of intemal store by giving priority to user processes, the impact on 
the performance of the virtual links and the processorwill be quite noticeable. User 
processes should only be given priority over the virtual channel support processes 
on a processor if the amount of data through-routed by the processor during 
normal operation is likely to be small. 
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Giving user processes priority use of fast memoiy will only impact the performance 
of those virtual channels used by processes on the processor. The CPU cost of 
supporting those virtual channels will only be slightly increased. 



10.2.4 Control of routing and placement 

This section describes how the allocation of a virtual routing system across a 
network can be controlled. For example, particular routes can be avoided or 
promoted as required. 

Introduction to routing and placement attributes 

User control of routing and placement is performed by means of three extra 
processor attributes routecost, tolerance, and linkquota. These are 
specified in the MAPPING section of the configuration file. They are specified for 
physical processor names using the following syntax; 

SET processomame {routecost := exp) 

SET processomame {tolerance := exp) 

SET processomame (linkquota := exp) 

Routing cost 

routecost can be used to make the configurer choose one processor 
over another when deciding how to route channels in the network. In the 
default case, all processors and links in the networi< are assumed to be 
equally usable. When deciding how to route a channel between two 
processors, the configurer works out the routes between the two points, 
and then calculates the "cost" of each route by counting the number of 
processors on each route. The "best" of these {the one with the least 
number of processors) is then chosen to implement the channel, and the 
appropriate through-routing processes are placed on each intermediate 
processor on the route. If there are a number of channels to be imple- 
mented between the two ends, and there is more than one route of the 
same ("best") length available, then the channels are shared between the 
available routes. 

routecost allows a muting cost to be explicitly allocated to one or more 
processors in the network. The cost of a route between two processors Is 
then determined not simply by the number of intermediate processors, but 
by the sum of the routing costs of all the intemiediate processors. There 
is a default routing cost for processors which have not had one explicitly 
allocated. So by giving a high routing cost value to a processor, this will 
discourage the configurer from using it as an intermediate node when 
routing channels. Similarly by giving it a low cost compared with other 
processors in the networi(, this will encourage the configurer to use it for 
through-routing. 
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A value greater than or equal to the maximum permitted value infi- 
nite, COST (defined in occonf .inc) prohibits through-routing on that 
processor 

Tolerance 

The second attribute - tolerance - controls how the configurer decides 
to share out channels between available routes. If there are a number of 
channels to be implemented between two processors, then the configurer 
normally calculates the cost of each possible route, and then shares out 
the channels between available "best" routes with the least cost. If there 
is only one "best" route then all the channels will go via that one. In some 
circumstances it may be better to share out the channels more evenly, to 
prevent bottlenecks in the system, even if this results in some channels 
being implemented on slightly higher cost routes. The tolerance 
attribute for a processor is designed to allow this. 

When calculating whether to use a route for channel sharing, the confi- 
gurer uses the minimum of the tolerance values of the processors on 
that route. It subtracts that tolerance from the route cost; if the result is less 
than the cost of the "best" route, then this route, as well as the "best" 
routes, may be used for load-sharing of channels. As an example, consider 
a network in which all processors have been given the same routing cost 
(say 1000). Normally, this would result in load-sharing of channels only 
when the routes are the same length. However, if the tolerance of all the 
processors were set to twice the routing cost value (2000), then the confi- 
gurer would also include routes with one more processor on them than the 
"best" route for channel load-sharing. 

When setting up a network, the routecost attributes should be set first 
to indicate which processors are prefen-ed for through-routing. Then the 
tolerance attribute can be set, for all processors in the nehvork, to influ- 
ence the load-sharing strategy. In general a set of processors in a network 
(or in part of a network) would be given the same tolerance value to indi- 
cate the load-sharing strategy required for that networic (or part of the 
network). The likely cases are: 

• A zero tolerance value indicates that virtual channels should only be 
placed on a route if it is the only "best" route between two processors. 
If all "best" routes have zero tolerance, then one will be picked arbitrarily 
and a// virtual channels will be routed on that one. 

• A default tolerance value indicates that channels may be shared 
between the "best" routes between two processors. 

• A tolerance value which is some multiple of the routing cost values 
in the network indicates that channels should be shared between the 
"best" routes and those routes with a higher cost but with tolerance 
values indicating that they are also acceptable. 
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• The maximum tolerance value indicates that a// routes between two 
processors can be used for channels. This might lead to some very long 
routes being chosen. 

ZERO. TOLERANCE, DEFAULT . TOLERANCE and HA3C. TOLERAKCE are 

defined in the include file occonf . inc. 
Link quota 

The third attribute - linfcquota - controls how many links on a processor 
may be used to cany virtual channels to the processes on that processor 
In the default case any of the four links may be used. For each link which 
is used, a small additional memory overhead \s incun-ed. On processors 
with very small amounts of memory it may be important to keep the 
memory overhead as low as possible. 

The linkquota attribute can be set to a value in the range to 4 inclusive. 
It should only be set to if no virtual channels will be required by the 
processes on that processor. If it is set to 1, then the processes on the 
processor may use virtual channels, but it should be possible for the confi- 
gurer to implement them all via one of the processor's links. Similarly for 
values of 2, 3, and 4 (although, obviously, setting the quota to 4 on a 
processor with four links has no effect). 

The linkquota attribute is a guide to the configurer rather than an abso- 
lute directive. If a processor has a linkquota value of 1 , but the processor 
provides the only route available for the implementation of a particular 
channel in the network, then the configurer will choose to route data 
through that processor, even though this will cause the link quota to be 
exceeded. 

The linkquolia is not intended as a method of avoiding routing through 
a processor; the routecost attribute should be used for that. Instead it 
is intended to indicate, on memory-critical pre)cessors, that the minimum 
overhead should be placed on them. The quota should reflect the require- 
ments of the processes placed on that processor, and the routing costs in 
the network should be chosen so that other processors are used for 
through-routing. The link quotas will then be checked by the configurer as 
it sets up the multiplexing and routing processes. The configurer will output 
a warning message if it has exceeded a quota. The network can then be 
re-examined to see why this is happening. 

The minimal spanning tree 

There is one aspect of the implementation of virtual channels which may become 
evident when constraints are placed on how the configurer may route channels in 
the network. Normally the configurer can use any of the links in the network for 
virtual channels, so if the network is connected, then virtual channels can be routed 
from any pnDcessor to any other. However, (as described in section 10.2.2) it is 
possible to place a pair of opposing channels on a link in the network; in this case 
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the (ink is used directly to implement those two channels, and cannot be used for 
virtual channels. Also the routecost attribute on selected processors in the 
network may prevent the use of some processors (and hence links) in the network 
for through-routing. If too many links are removed from the network in this way then 
it may become impossible to implement some of the virtual channels required. 

So it is important to ensure that, for a set of processors in a network requiring virtual 
channels to be connected between them, there is a set of links connecting the 
processors over which virtual channels is allowed. This set of links will then be 
used by the configurer to construct a minimal spanning tree of links to ensure that 
it can always implement the virtual channels between these processors. Any addi- 
tional links available for virtual channels will also be used to provide better routes 
between processors. If the configurer is unable to construct the route necessary 
to implement a requested virtual channel, it will give an en-or message. 

A networic may not require a single minimal spanning tree to cover the whole 
network; it depends on the virtual channel requirements of the configuration. For 
example, it might be possible to divide a configuration into two separate parts, 
each requiring virtual channels internally, but wth a single pair of channels {which 
can be directly mapped onto a link) joining the two parts. In this case a minimal 
spanning tree of links is required for each of the two parts. These are known as 
sub-networks. 

Summary of routing and placement attributes 

The attributes are defined in more detail as follows: 

• routecost - defines, within the range MIN . COST to MAX . COST inclusive, 
the associated cost of routing virtual channels through a particular 
processor Default values of 1 and 1000000 respectively are defined for 
these constants in the Include file occonf , inc 

If a value greater than the maximum of MAX . COST (e.g. INFINITE . COST) 
is specified then no through-n^uting will be permitted on that processor 

The default value for this attribute is 1000 i.e. DEFAULT. COST. 

• tolerzmce - contnDls how much a particular processor can be used to 
provide load-sharing nauting paths for other processors. It uses any value 
in the range ZERO . TOLERANCE = to MAX . TOLERANCE =1000000 inclu- 
sive. 

The default value for this attribute is 1 i.e. DEFAULT . TOLERANCE. This 
allows the processor to implement alternate routes for through-routed 
channels with exactly the same total cost as the "best" route found 
between any two other processors. 

If the value ZERO . TOLERANCE is specified then the processor will only be 
used for through-routing if it lies on the "best" nsute found to implement 
virtual channels. 
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if tiie maximum vaiue MAX. TOLERANCE is specified on all processors in 
the target network almost every possible route will be used to share the 
cost of canying data between any pair of non-adjacent processors. 

• linlcquota - suggests the maximum number of links on the processor 
that should be used by the virtual channel routing system. 

linkquota can have the values to 4 inclusive. 

A warning will be produced if the suggested linfcquota for a node is 
exceeded. The linkquota will only be exceeded because of the require- 
ments of through-routing data for other processors. 

Default values for these attributes are defined in the include file occonf .inc 
which is supplied with the toolset. 

Prevention of through-routing via critical processors 

If there are processors within the target networic that are likely to be CPU-limited 
by the application, then it may be undesirable to allow virtual channels from 
surrounding processors to be routed through the performance-critical processors. 
In this case the routecost attribute for the critical processors should be set to 
INFINITE .COST If this Is done then no virtual channels can be through-routed 
via these processors. 

Care must be taken to ensure that a minimal spanning tree of links is provided by 
the other processors in the networit. If a particular processor should only be used 
for through-routing channels when absolutely necessary, then the routecost 
attribute on the processor can be set to some multiple of the default value. Altema- 
tively fie cost value can be explicitly set on the other processors. If for example, 
the multiple concemed is larger than the number of lower cost processors in the 
networit then any route via those processors will be chosen in preference to a route 
via one of the high cost processors. 

Use of additional processors for through-routing 

There may be situations when the configurer is required to route all communica- 
tions via a particular set of processors. For example: 

• to emulate closely the communications stmcture that would be provided 
by dedicated hardware routing devices, or 

• when a block of low performance processors is provided in the target 
network solely for the purposes of through-routing data for other proces- 
sors. 

This can be achieved in one of two ways: 

• If the routecost of all processors, other than those intended as routers, 
is set to INFINITE . COST then the only processors that the configurer can 
use for through-routing are those left with the default routing cost. This 
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technique has the advantage of guaranteeing that no through-routing will 
be done via the standard processors. 

• If the routecost of ad the routing processors are set to a small value then 
any route via these processors will be used in preference to routes via 
processors with the default routing cost. This technique has the advantage 
that the normal processors can still be used by the configurer for routing 
channels that cannot be implemented by the nommated routing proces- 
sors. Hence the nominated routing network need not provide full connec- 
tivity. 

Generally the second method is preferred as it preserves the ability of the confi- 
gurer of mapping an arbitrary application onto the target hardware. 

Support for memory-critical systems 

It may be desirable to ensure that for a particular processor the additional run-time 
overhead added by the configurer is kept to a minimum. 

Normally the configurer spreads virtual channels running between a pair of 
processors across all routes that have equal cost. For each additional route 
employed additional support processes may be required and hence additional 
memory consumed on the target system. 

This should not normally be a problem as the total cost of the maximal set of run- 
time processes that can be placed on the target system by the configurer 
consumes only a few thousand bytes more than the minimal set. 

Some example figures of the minimum and maximum costs of both through- 
routing and multiplexing software on different word length transputers are shown 
below {all sizes are in bytes): 



Word Size 


Function 


Code 


Min Stack 


Max Stack 


32 bits 


Through-routing 


699 


768 


2112 


Multiplexing 


1940 


784 


2056 


16 bits 


Through-routing 


708 


512 


1568 


Multiplexing 


1952 


524 


1556 



Multiplexing software is needed whenever a processor has virtual channels termi- 
nating on it. In the current system each opposing pair of virtual channels fonning 
a virtual link wilt require approximately 120 bytes of local storage on a 32-bit 
processor and 80 bytes of storage on a 16-bil processor 

Note: In the default configuration case, extra overheads will be incurred to allow 
interactive debugging of the application. Use the Y command line option to over- 
ride this. 

A particular case of the critical memory problem comes when the set of user 
processes on a particular processor do not in themselves require virtual channels 
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at all, because the channels they use can be mapped directly onto the hardware 
links available. However, if the configurer decides to use through-routing then 
through-routing support processes will be added to the processor. In addition, to 
enable the available hardware finks to be shared, some of the channels used on 
the processor may be implemented as virtual channels. In this case multiplexing 
software will also be required. In this special case the processor can be completely 
protected from run-time overheads by using the techniques described above 
under the heading Prevention of through-routing via critical processors. 

A linkquota attribute can be specified on each processor in the target network. 
If the linkquota of a particular processor is specified as 1 and the routecost 
set to INFINITE, COST, then only a single hardware link will be used on the 
processor to provide all the virtual channels it uses. In addition the memory over- 
heads of the virtual link system will be reduced to a minimum (minimal multiplexer 
only). 

If linkquota Is set to 1 on all processors in the target system then the minimal 
spanning tree of links will be used to support all virtual channels required. Warn- 
ings will be produced in this casefor all processors that have had more than link- 
quota links used on them; this is because all processors cannot be chosen as 
"leaves" in the spanning tree. 

If both performance and memory size are a problem in a particular system it is likefy 
that the user will have to tune the linkquota and tolerance parameters of 
many processors in order to get the best result. 



10.3 Example - optimized filter test program 

Figure 10.3 describes an example configuration that needs to be placed onto a 
network of six processors (Figure 10.4). The ftjnction of the program is to test the 
two filter components which are limited by the speed of the processors concerned. 
Sources are supplied in the exanples/manuals/advconf directory. 
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Figure 1 0.3 Example filter test program 
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Figure 10.4 Example filter test hardware 

This is not a real program but has been constructed to demonstrate many of the 
features for optimization described in the previous sections, within a comparatively 
small and simple system. Tl^e basic configuration description is listed in the 
following example: 
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— Include values for router attributes 
#INCLUDE "occonf .inc" 

— Hardware description for specialised 9t3b-system 

NODE GENERATE, FILTERA, FILTERB : 
NODE RESULTA, RESULTS, l«)NI!rOR : 
EDGE pottlf port2 : 
ARC hoatarc : 

— The following ARCs are only required vh^n optimising 
ARC GENERATE. TO. FILTERA, GENERATE. TO. FILTERB : 

ARC FILTERA. TO. RESULTA, FILTERB. TO. RESULTB : 



IfETHORS 
IX) 

SET GENERATE <typ«, 

SET FlLTERA {type, 

SET FILTERB {type, 

SET RESULTA (type, 

SET RESULTS <type, 

SET MONITOR (type, memsize 



"TSOO", 32*K) 

"T425", 128*K) 

"T425", 128*K) 

"T425", 128*K) 

''T425", 12S*K) 



"T425'' 



2*M) 



CONNECT HOST TO 

CONNECT HDKITOR[lin]c] [2] TO 
CONNECT M3NIT0R[link] [3] TO 
CONNECT M3NIT0R[lin]c] [0] TO 
CONNECT GENERATE [link] [1] TO 

GENERATE . TO . FlLTERA 
CONNECT GENERATE [link] [2] TO 

GENERATE . TO . FILTERB 
CONNECT RESUlTA[link] [2] TO 

FlLTERA . TO . RESULTA 
CONNECT REStTLTB [link] [1] TO 

FILTERB . TO . RESULTB 
CONNECT REStrLTA[linfcJ[3] TO 
CONNECT RESULTB [link] E3J TO 



MONITOR [link] [1] WITH hostarc 
RESULTA [link] [1] 
RESULTB [link] [0] 
GENERATE I link] [3] 
FlLTERA [link] [2] WITH 

FILTERB [link] [1] WITH 

FlLTERA [link J [1] WITH 

riLTERB[link] [2] WITH 

FlLTERA [link] [0] 
FILTERB [link] [0] 



CONNECT GENERATE [link] [0] TO RESULTB [link] [2] 

CONNECT FILTERA[link] [3] TO portl 
CONNECT FILTERB[link] [3] TO port2 



— Software description for filter test program 

NODE generate. p, monitor. p 7 
[2]N0DE result, p, filter.p : 

#INCLDDE "hostio . inc'' 
#USE "generate, cSh" 
#USE "filter. c5h" 
iUSE "result. c5h" 
#USE "ironitor . cSh" 

CHAH OF SP fs, ts : 

[2] CHAN OF BYTE Out : 

[2] CHAN OF BYTE Filter .to. Res : 

CONFIG 

[21CHAN OF BYTE Res : 
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[4] CHAN OF BYTE Cntl : 
PAR 

PROCESSOR monitor. p 

Monitor ( f s ^ ts ^ Res j Cntl } 
PROCESSOR generate. p 

Generate (Out) 
PAR 1 = FOR 2 
PAR 

PROCESSOR result. p[i] 

Result(Filter,to.Res[i], Res[i], Cntl[i]) 
PROCESSOR filter. p[i] 

Filter (Out [i] , Filter .to. Res [i] , Cntl[i+2I) 



— Mapping description 
M&FPINQ 
DO 

MAP gene r ate. p ONTO GENERATE 

MAP filter. p[0] ONTO FILTERA 

MAP filter.pEl] ONTO FILTERS 

MAP resialt.pfOJ ONTO RESULTA 

MAP result.p[lj ONTO RESULTB 

MAP monitor.p ONTO MONITOR 

MAP fs, ts ONTO has tare 

— Mapping optimisation: 

— Prevent through routing via GENERATE 
SET GENERATE (routecoat := INFINITE. COST) 

— Ensure minimuia overhead on FILTEEUL 

SET FILTERA (routecost, linlcqpiota := INFINITE. COST, 1) 

~ Ensure minimuin overhead on FILTERS 

SET FILTERS (routecost, linkquota := INFINITE. COST, 1) 

— Optimise Generate to Filter Q Path 
MAP Out[0] ONTO GENERATE.ro. FILTERA 

— Optjiniae Generate to Filter 1 Path 
K^ 0ut(l] ONTO GENERATE. TO. FILTERS 

— Optimise Filter to Result Path 

MAP Filter. to. Res[0] ONTO FILTERA. TO. RESULTA 

— C^tinaise Filter to Result 1 Path 

MAP Filter, to. Res [1] ONTO FILTERS . TO . RESULTB 

— Use otherwise unspecified linkquotas to check 

— overheads on GENERATE, RESULTA, and RESULTB 
SET GENERATE (linkquota := 0] 

SET RESULTA (linJcquota := 2) 
SET RESULTB (linfcquota := 2) 



For this real-time program to actually work correctly a number of optimization 
features of the configurer have been exploited to ensure the right routing decisions 
are made: 
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• GENERATE has no memory space available to carry the overheads of 
routing software and requires no virtual channels itself, so setting route- 
cost to INFINITE .COST prevents routing software being placed on it 

* FILTERA and FILTERS must be operated in a state as dose as possible 
to the real case, where all their channels are placed onto hardware links. 
The main data path through the Filter component must operate at hard- 
ware data rates, so the In and Out channels must both be piaced onto 
hardware links to guarantee the required performance. The Cntl channel 
which cam'es a small amount of parameterization data can^ however, be 
implemented as a virtual channel without significant effect. 

These are implemented in the Mapping description. 

Note: the example should be built with interactive debugging disabled so that 
explicit channel mapping can take effect. 
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This chapter describes the mechanisms for mixing code modules written in 
different high level languages. It is divided into two parts. Tlie first part discusses 
how to call procedures and functions written in one language from another 
language. This includes details of the library procedures provided to allow Occam 
programs to call C functions which require use of static or heap memory. 

The second part describes how complete C programs can be called as if they were 
Occam processes with a standard channel interface. 



11.1 Mixed language programs 

For many applications It is appropriate to write the software using more than one 
programming language. For example^ a particular algorithm may be better 
expressed in a specific language, or application modules may already exist in 
particular languages. In either case a well defined mechanism for mixing 
languages within a single system is desirable. 

The toolset provides a clean and simple basis for mixing languages on transputer 
networks. Independent software processes can be written in different languages, 
compiled and linked using a common set of tools, and the linked modules placed 
anywhere on a networic of transputers using a configuration description. Compiler 
pragmas are provided to allow code to be imported wjth the con^ect calling conven- 
tions, and to translate names so they are valid in the calling language. 

Code written in other languages can be used as external routines in a program, 
providing the language calling conventions are honored, and no conflicts of name 
occur. 

There are a number of issues to be considered when mixing languages. These are: 

• The declaration of the external routine — in order for the calling program 
to be able to correctly call an extemal routine, it must have a descn'ption 
of the interface to the routine. The way in which this is done depends on 
the language being used. 

• The translation of names — programming languages differ in the legal 
character set for identifiers and symbolic names. Thus, names acceptable 
in one language may not be valid in another. To avoid these problems 
compiler pragmas are provided to peri'orm name translations. 
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• The calling conventions of the languages — including passing the address 
of the static area and the types of the parameters in the two languages. 

• The types returned by functions. 

• The presence, or otherwise, of a static area in each language (this is 
discussed in more detail below). 

• The libraries to be used when linking the complete progran^. 

These issues are discussed in more detail in the the following sections. 

Note: When mixing languages, the external procedures must not do any host 
communications. All i/o should be performed by the calling program. The external 
procedures can however perform channel communications with other processes. 

HAA Declaring external routines 

In order to properly call a separately compiled procedure or function, the compiler 
needs to be given information about the external routine. In C this is done by 
declaring the function as external, for example: 

extern int f {int a, int b) ; 
extern void pi (char c) ; 

The functions should be declared as prototypes, including the types of parameters, 
to ensure that the actual parameters are converted to the specified types. If the 
functions are declared vrithouf the parameter types then the default C argument 
type promotions will take place. 

The Occam compiler uses a pragma to provfde information about external proce- 
dures and functions. The syntax of this is: 

f PRAGMA EXTERNAL "formal dBdaration = wxkspace[f vectorspace]" 

The optional parameter vedorspace is not required for C functions. 

For example: 

fPRAGMA EXTERNAL ''PROC pi (VAL BYTE c) = 20^" 
fPRAtaa EXTERNAL ''FR0C p2 (BYTE x, y) = 40, 100" 
fPRAGHA EXTERNAL 'INT FDNCTXQN £ (VAL INT a, b) = 50'' 

A vokj function in C is equivalent to a procedure in occam. 

11.1.2 Translating identifiers 

Because the syntax of valid identifiers can vary from one language to another, 
compiler pragmas are provided in G ar>d occann to allow the names used in a 
source file to differ fi^xn those used externally. 
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The pragma can be used to change the name which is used in the object code to 
reference an external routine. For example, a C program which needs to call an 
Occam function called 'get. next' could use the following to convert the name 
into a valid C identifier 

#pragma IMS_translate{get_next, "get. next") 

extern void get_next(int *n; Channel *in) ; 

Alternatively the pragma could be used to change the name 'exported' from the 
Occam code: 

#PRAGM2l TRANSLATE (get. next, "get_next") 
PROC get. next (INT next, CHAN input) 



In this case, the object fite will contain the name 'get_next' and the procedure can 
only be called by this name, 

1 1 .1 .3 Parameter passing 

The two issues In passing parameters between languages are, firstly^ the types of 
the formal and actual parameters (Including whether they are passed by value or 
by reference) and, secondly, the use of a static area by each language. These are 
described in more detail below. 

Parameter compatibility 

Correct parameter passing depends on the compatibility of data types between 
languages. See the language implementation chapters of the appropriate 
Language and Libraries Reference Manual for details of the implementation of 
types and how parameters are passed. 

The way in which parameters are passed ~ either as a copy of the data (by value) 
or a pointer to the data (by reference) — involves two issues: the semantics of the 
language, and the actual implementation. 

C: All parameters are passed by value. Arrays are passed as pointers to 
the base type of the array. It is possible to pass pointers to variables which 
gives the effect of passing by reference. 

Occam: parameters are either VAL parameters or non-VAL parameters. 
VAL parameters may be implemented by passing by value, or by passing 
a pointer. The latter will happen when the size of the parameter is larger 
than the word length of the processor and will therefore depend on the data 
type and the processor type. 
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Types can be considered to be compatible if they have the same interpretation, are 
the same size and are passed in the same way. For example, a C parameter of type 
int is compatible with an Occam val int parameter. Similariy, as an occam 
INT parameter is passed as a pointer it is compatible with a C int * parameter. 

When passing parameters the correct data type should be used. Equivalences for 
the main C and occanri data types are listed in tables 11.1 and 112. 



Occam type 


Ctype 


YAL BYTE 


char 
iinsigned char 


BYTE 


char * 
unsigned char * 


VAL INT16 


short int 


INT16 


short int * 


VAL INT 


int 


INT 


int * 


INT32 


long int * 


ke:al32 


float * 


VAL REAL64 
R£AL€4 


double * 


CHAN 


Ch?*nnel * 


TIMER 


No parameter required 



Table 11.1 Type equivalents for all processors 



Occam type 


Ctype 
16 bit processor 32 bit processor 


VAL INT32 


long int * 


long int 


VAL REAL32 


float * 


float 



Table 11,2 Type equivalents dependent on processor word length 

Comprehensive equivalence tables, with examples of calling extemal routines 
from each language, can be found in Appendix B. 

Range checking in occam 

It is important to ensure that parameters passed to Occam procedures and func- 
tions from C have values within the legal range for the type. For example, when 
passing to a formal parameter of type byte the value must be in the range 
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through 255. Violation of this rule is liable to cause a mntime range check error in 
the Occam code. 

Occam timers 

An Occam TIMER parameter should have no assodated actual parameter. For 
example, consider the following occam procedure : 

PROC p iVHL INT plr TIMER t, VAL INT p2} 
SEQ 



The C code to call the above is as follows: 

void p(int pi, int p2) ; 
tfpragma IMS_nolinlc{p) 

int X, y; 

p(»/ y); 



11.1.4 Passing array parameters 

In both C and occam an array parameter is passed as a pointer to the start of the 
array, i.e. the address of the first element, occam also supports unsized array 
parameters where some or all of the an-ay bounds may be omitted from the param- 
eter declaration. In this case the address of the array is followed by a sequence 
of integerparameters, one for each unknown bound, giving the value of that bound. 
The unknown bou nd parameters appear in the sa me order as the unknown bounds 
in the anay parameter declaration. 

In the following sections OCCam procedures are used in the examples. The prin- 
ciples described apply equally to Occam functions except that an occa m function 
may only have VAL parameters. 

C calling occam 

There are four cases to consider when calling Occam routines, which accept 
an-ays as parameters, from C. In the following examples we assume that the C 
declaration of the Occam routine has the nolinfc pragma applied to it so that the 
hidden Global Static Base (GSB) parameter is not passed when we call the 
occam routine (see section 11.1.6). Although the examples use int arrays, the 
same principles apply to an an-ay of any other occam type. 

1 Sized array: 

PROG f([8]INT a) 



72TDS366 01 March 1993 



204 1'1-1 Mixed language programs 

To call the above from C we can declare the Occam procedure as a C prototype 
in any of the following ways: 

a) void f {int aI83) ; 
bjvoid f (int a[]) ; 
c)void f(int *a) ; 

The function is called as follows: 
int a[8J; 
f(a); 

2 Sized VAL array: 

PSOC f(VAL [8] INT a) 

This is similar to case 1 except that since the array is a VAL array we can declare 
the Occam routine as a C prototype which accepts a const an-ay. 

a) void f (const int a[8]); 
b)void f (const int a[3); 
C)void fC const int *a) ; 

The function is called as follows: 

int a [8] ; 

f(a); 

3 Unsized array: 

PROC f([]INT a) 

Here the Occam procedure expects a hidden Integer parameter following the 
array which gives the number of elements in the array. Thus we can declare this 
Qcoam routine as a G prototype as follows: 

a) void f(int &[}, const int size}; 
b)void f{int *a, const int size) ; 

The function is called as follows: 

int a [8] ; 
f(a, 8); 

4 Unsized VAL array: 

PROC f(VAL t]INT a) 
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This is similar to case 1 except that since the array is a val array we can declare 
the Occam routine as a C prototype which accepts a const array. 

a)void f (const int af] , const int size) ; 
b)void f (const int *a.r const int size) ; 

The function is called as follows: 
int a [8] ; 
f(ar 8); 

Multi-dimensional arrays (C calling OCCam): 

Multi-dimensional arrays are treated in the same way as that described for unitary 
arrays. The hidden array dimensions are passed in the same order as they appear 
in the an-ay definition. For example, consider the following occann routine which 
is to be called from C: 

PROC f ([8] [] []INT a) 

This can be declared as the following C prototype: 

void f (int a[8] [] [J , const int boundl, const int bound2) ; 

#pragma IMS_nolink (f ) 

Note that even though the array has three dimensions we only declare explicit extra 
parameters for those dimensions that are hidden. 

This function can be called as fofEows: 

int a[8] [9J[4]; 

f{a, 9, 4); 

Occam calling C 

There are a number of cases to consider when calling C routines, which accept 
arrays as parameters, from Occam. In the following examples we assume that the 
C functions to be called have been declared using the noXink pragma so that we 
do not need to pass a hidden GSB parameter (see section 11.1 .6). Although the 
examples use int arrays, the same principles apply to an an-ay of any other C 
type. 

1 Sfmple arrays and pointers 

a) void f (int a[8]) ; 
b)void f (int a[]) ; 
C) void f (int *a) ; 
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These would be declared as an OCCam procedure and called as follows: 
#PRAGMA EXTERNAL "PROC f {[8]INT a)=ws" 
[8] INT a: 

Note that b) and c) cannot be declared as accepting unsized airays in occam 
because they are not expecting the hidden parameters that occam would pass 
implidtiy when f was calJed. 

2 const arrays and pointers 

a) void f (const int a[8J); 
b)void f (const int a[]); 
c)void f (const int *a) ; 

These would be declared as an occam procedure and called as follows: 

#PRAGMA EXTERNAL "PROC f (VAL [8] INT a)=W3" 

18] INT a: 

f(a) 

Note that b) and c) cannot be declared as accepting unsized arrays in occam 
because they are not expecting the hidden parameters that OCCam would pass 
implicitly when f was called. 

3 Arrays and pointers accompanied by size values 

It may be that the C function to be called is written in such a way that it expects an 
integer to follow the array which gives the number of elements in that array. This 
matches the parameter passing conventions for occam unsized arays. Thus if 
the C function is defined as follows: 

a)void £(int a[] , const int s) ; 
b)void f(int *a, const int a); 

then the equivalent Occam declaration and call is: 

#PRAGMA EXTERNAL "PROC f([IINT a)=ws'' 

[8] INT a: 
f(a) 

When f is called occam implicitly passes the array bound, 8, which is picked up 
as s by the C function. 
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4 const arrays and pointers accompanied by size values 

This is similar to the above but the array in the Occam declaration of the C function 
is now declared as a val array Thus given the following: 

a) void f (const int a[], const int s) ; 
b)void f (const int *a, const int s) ; 

then the equivalent occam declaration and call is: 

#PRAGMA EXTERNAL "PROC f(VaL []INT a)=ws" 

[8] INT a: 
fCa) 

Multi-dimensionai arrays (occam calling C) 

Multi-dimensional arrays are treated in the same way as unitary arays. For 
example, consider the following C routine which we want to call from occam: 

void f (int a [3 J [4]) ; 

then the equivalent occam declaration and call is: 

#PRAGMA EXTERNAL "PROC f ([3] [4] INT a)=ws" 

[3] [4]INT a: 
f(a) 

Occam expects any hidden an^y dimensions to l>e passed in the same order as 
they appear in the an-ay definition. Consider the following C routine, which expects 
the an-ay bounds to be passed separately and which we want to call from occam: 

void f(int *a, const int boundl, const int bound2) ; 

The equivalent occam declaration and call is: 

#PRAC31A EXTERNAL "PROC f ([] []INT a)=ws" 

[3] [4]INT a: 
f{a) 

When f is called in this case the C function will receive 3 for boundl and 4 for 
bound2. The bounds are passed implicitly by occam. 

11.1.5 Function return values 

When functions are being called It is also necessary for the return types to be 
compatible. 
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The definition of compatibility for function return types is stricter than that for 
parameters. Floating point and integer function results are returned in different 
ways (depending on the processor type) and so it is essential to ensure that the 
types of function return values are strictly equivalent. A partial list of equivalents 
is given in table 11. 3 for guidance. Comprehensive tables of equivalent types can 
be found in Appendix B. 



Occam function type 


C function type 


BYTE 


char 
unsigned char 


INT32 


long int 


INT 


int 


REAL32 


float 


ke:al64 


doTible 



Table 11.3 Equivalent function return types 
As an example, consider the C tijndion cfun which returns int: 
int cfun (int a); 
fpragioa IMS_nolink(cfun) 
int cfun (int a.) 

i 
} 

This would be called from occam as an int function as follows: 

#PRAGMA EXTERNAL "INT FUNCTION cfun (VAL INT x) = 20" 
Cfun (42) 

C function type void 

A C function of type void must be called from OCcam as a PROC. For example: 

void cfun (int a); 

tpragma IMS_nolink(Gfun) 

void cfun (int a) 
{ 

} 
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This can be called from Occam in the following way: 

#PRaGMR EXTERNAL "PROC cfun (VAL INT x) = 20'^ 
cfun(42) 
Similarly, an occam PROC must be called from C as a void function. 

Restrictions on functions that may be called 

Because occam functions can only have val parameters, and these do not 
always have C equivalents, there are restrictions on the types of occam functions 
that can be called from C and vice-versa. For example, there are no equivalents 
of the occam bool type and so functions which require this type of parameter 
cannot easily be called. 

Similarfy, because C functions can only return a single value, only occam func- 
tions with a single return value can be called from C. 

occam cannot call C functions which return structure types, 

C functions that are called by occam must not modify any global variables, that 
is, they must be free from side-effects. 

11.1.6 Global static base parameter 

C uses an area of memory for static data. This requires a parameter to be passed 
to the called function to enable it to access the static area — this parameter is 
known as the Global Static Base or GSB. This parameter is added automatically 
by the compiler and is not normally visible to the programmer. 

Occam differs from C in that it does not use a static or heap area and so does not 
expect a GSB parameter to be passed to procedures. Similarly, occam programs 
do not pass a GSB pointer when procedures are called. In order to allow calls to 
work correctly between languages the presence of the GSB parameter must be 
taken into account. 

There are two possible solutions to this problem: 

1 A dummy GSB parameter can be provided in OCCam. 

2 A compiler pragma can be used in the C program to specify that a function 
does not require a GSB parameter. 

3 When calling occam from C, make use of the caii_without_gsb func- 
tion (see the ANSI C Toolset Language and Libraries Referer)ce Manual). 

The first two techniques can be used either on the routine being called or in the 
calling program, whichever is more appropriate. 
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In the examples below which show C functions called from Occam, it is assumed 
that the C code does not use any static or heap memory. However, it will often be 
necessary for the Occam calling program to allocate some memory for use by the 
G code as the static or heap area; a pointer to this memory is then passed as the 
first parameter when the Unction is called. This technique is described in more 
detail in section 11.1.8. 

Method 1 — dummy GSB parameter, 

A dummy parameter can be used either as a foiinal parameter for procedures 
which are to be called from C, or as an actual parameter for C functions which are 
being called from Occam. For example the following occam function can be 
directly called from a C program: 

INT FUNCTION ocftinc(VaL INT GSB, argl , arg2) 
— Note: dummy parameter GSB is not used 
INT return: 
VIOJOT 

RESULT retnirn 



Note: because the dummy parameter is not used, the Occam compiler will 
generate a waming message but correct object code is still generated. 

To call this version of ocf unc from a C program it is declared as an extern func- 
tion (without the GSB parameter) and then called normally: 

/* declare function as external */ 
extern int ocfunc(int argl; int arg2) ; 

/* call function */ 
ret = ocfunc(x, y) ; 

The same method can be used to call a C fijnction from Occam by passing a 
dummy first parameter of type int. For example the C function: 

void Gfun(int a) 

{ 
I 

J 

Could be called from Occam in the following way: 

#PRAGMa EXTERNAL ''PROC cfun <VAL INT GSB; x) - 20" 

VAL INT GSB IS 0: 
cfunCGSB, 42} 
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Method 2 — nolink pragma 

In order to simplify mixing occam and C, the INMOS C compiler provides the 
IMS_nolin]c pragma which directs the specified function to be compiled without 
the static link parameter. Any calls of the function, within the scope of the pragma, 
will not have the GSB. added to the parameter list. If the function is de/7nec/ within 
the scope of the pragma then it will be compiled without the requirement for a static 
link parameter (the compiler will flag a serious error if the function requires access 
to static data). 

As an example, consider the OCCam function ocfunc below; 

INT FUNCTION ocf unc (VAL INT argl , arg2) 
INT ret : 
VALOF 

RESULT ret 



To call ocfunc from a C program it must first be declared as an extern function 
and then specified as not requiring the GSB parameter 

/* declare function as extremal */ 
extern int ocfunc (int argl, int arg2) ; 

/* specify that function has no GSB parameter */ 
#pragina IMS_nolinIc (ocfunc) 

/* call function */ 
ret = ocfunc (x, y) ; 

The same technique can be used to compile a C function which does not require 
a GSB parameter so that it can be called directly from occam. As an example, 
consider the C function betow: 

/* declare function before referencing */ 
void cfun(int a); 

/* specify that function has no GSB parameter */ 
#pragma IMS_nolin3c(cfun) 

/* define the function */ 

void cfun(int a) 

{ 

} 
This can be called from Occam in the following way: 

#PRAGMA EXTERNAL "PROC cfun (VAL INT x) = 20" 

cfun(42) 
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Method 3 — using call_without_gsb function 

This method is applicable only when dynamically loading code using the ANSI C 
Toolset. It is described in the ANSI C Toolset User Guide. 



11. U Linking the program 

After all the component parts of the program have been compiled, they must be 
linked together with any libraries required- The libraries that are required will 
depend on a number of factors such as the language that the main (calling) 
program is written in, whether the program communicates with the host, which 
library routines are used by the different language modules. Some guidelines for 
various configurations are given below. 

Calling Occam from C 

When calling Occam code from a C program, then the following library files must 
be linked with the compiled Occam and C code. 

• The C runtime library 

If the program uses the host file server then the fu// runtime library must be 
used. This can be linked in by using the linker indirect file cstartup. Ink. 

If the program does not use the host file server then the reduced runtime 
library must be used. This can be linked in by using the linker indirect file 
cstartrd.lnk. 

• The standard Occam compiler libraries will be required by most occam 
code. These libraries can be linked in by using the appropriate 
occamx. Ink linker indirect file. 

• Any other C or occam modules or libraries referenced by the program 
must also be linked in. 

Calling C from occam 

When calling C code from an Occam program, then the following library files must 
be linked with the compiled C and occam code. 

• The standard OCCam compiler libraries can be linked in by using the 
appropriate occaoix. Ink linker indirect file, 

• If the main program is written in occam and allocates static or heap 
memory for C functions using the library procedures described in section 
11.1.8, then the library callc* lib must be linked in. 

• Any other C or occam libraries used must also be linked in. 
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• The reduced C library must be used as the calfed functions cannot make 
any host file server requests. The reduced runtime library can be IJnl<ed in 
by using the clibsrd. Ink linker control file. 

11.1.8 Allocating memory for C functions called from Occam 

The C runtime environment automatically provides C programs with a static area 
(for holding static data and extemal variables) and a heap area (for memory alloca- 
tion). However occam does not provide these and so this memory must be explic- 
itly allocated by the calling program before C functions are called. Four routines 
in the Occam library callc. lib are used to set up and terminate C static and 
heap areas from Occam for C functions that require them. 

The static area 

C static data is stored in a reserved area of memory called the static area which 
must be set up by the system and initialized. Each C function which uses static data 
needs to be able to find this area. In order to do this, every C function is passed, 
as the first parameter, a pointer to the start of the static area, the global static base 
(GSB). The static area must be set up and the GSB parameter passed explicitly 
by the calling Occam code. This means that a call to a C function from Occam will 
have one extra parameter compared to an equivalent cali from C. 

The heap area 

The heap area is that area of memory from which the C memory allocation func- 
tions reserve their memory space. It is separate from the static area and requires 
a static area to be previously allocated because infomiation about the heap is held 
in static variables. 

The heap need not be set up tf it is not ^equired^ but rememberthat it may be used 
implicitly by a library call. 

Providing static and heap 

Some simple C functions may not require static or heap areas and may be called 
more easily without using the special library routines. When calling a C function 
therefore, the first step is to decide whether static and heap areas are required. 

Deciding whether a static area is required 

For many C functions it may not be immediately obvious whether static or heap is 
required (the heap area requires a previously set-up static area). For example, 
some, but not all, library functions require static and heap areas and so, because 
it would be difficult to distinguish those that do, a static and heap area should be 
assumed whenever a library function is called. 

Because of the difficulty in covering all types of functions, the following series of 
rules is offered as a way of determining whether a function requires static or heap. 
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The rules inciude the most common reasons for a C function requiring static or 
heap memory. 

• If the function uses static variables then static is required. 

• If the function accesses external variables then static is required, 

• If the function includes an automatic structure or union initializer then static 
is required. 

• If the function uses any functions from the runtime library then static and 
heap may be required. 

Functions which fail all the above tests will probably not require static or heap, and 
can be called without using any of the static or heap library functions. 

Calling functions which do not require static or heap 

C functions which do not require static or heap can be called as described in 
section 11,1.6. 

Calling functions which do require static or heap 

For G functions which require static and/or heap the space must be set up in the 
Occam code before the function is called, and tenninated when no longer 
required. These operations are perfonned by procedures supplied in the library 
callc.lib.This library is supplied as part of the ANSI C toolset— do nof use any 
previous version of the library which was supplied as part of an Occam toolset. 

The library callc. lib provides four Occam procedures for initializing static and 
heap areas and terminating them after use. The routines are summarized In table 
11 .4 and described in more detail below. 



Procedure 


Description 


init. static 


Initializes an area of memory for use as the 
static area. 


init.heap 


Initializes an area for use as the heap area. 


terminate . heap . use 


Terminates heap usage. 


terminate . static , use 


Terminates static usage. 



Table 11,4 Library procedures to support memory allocation 

PROC init-static{[]INT static. area, INT required- size, GSB) 

init. static is used to set aside and initialize an area of memory for use as a 
C static area before any functions are called. The static area is declared as an 
integer anay in the calling Occam program. 
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Two integer values are retumed in tiie prccedure parameters: 

required, size The numberofwords Of Static space required. 

GSB A pointer to the base of the an-ay which wiJI act as the 

globai static base. 

Note: the size of the integer array is equivaienf to the number of words of static 
space required. One element of the integer an'ay is equivalent to one word of 
memory, if an en-or occurs on initializing the static area the value MOSTPOS INT 
is retumed instead of the required size. 

The procedure can be used to check the size of static area required by checking 
the value returned in the second parameter. For example; 

#USE "callc.lib" 

INT required. size r GSB: 
[STATIC. SIZE] INT stiaticarea: 

SEQ 

init. static (static . area ; required. size , GSB) 
IF 

required. size > STATIC. SIZE 

not enough space reserved 
TRUE 

array is big enough 

Another possible way of using init. static is to reserve a large amount of 
memory for use by the C function. To do this an initial call to init. static would 
be made with an array size of zero to obtain the required size, followed by a second 
call which would set up a segment of memory as the static area. The rest of the 
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memory could be used by the OCCam program for its own purposes, perhaps to 
allocate the C heap. For example: 

#USE "callc.lib" 

INT required, GSB: 

[VERY. BIG. NUMBER] INT memory : 

SEQ 

— check the static requirement 

init, static ( [memory FROM FOR 0], required, GSB) 

— allocate required amount of memory for static 
static. area IS [memory FRC^ FOR required]: 

— rest is available for other purposes 
memory, left IS [memory FROM required FOR 

(VERY. BIG, NUMBER - required)]: 
SEQ 

— now use allocated memory as static 
ini t . static ( s ta tic , area , required , GSB ) 
rest of program 



PROC ini t, heap (VAL INT GSB, HINT heap, area) 

ini t . heap is used to set aside an area of memory for use as a C heap before any 
C functions are called. The first argument is the GSB pointer returned by 
init, static, which is required because the memory allocation routines make 
use of static data. 

Like the static area, the heap area is declared as an integer array This array must 
be large enough to accommodate all calls to the C memory allocation functions. 
The size of the integer array is equivalent to the number of words of heap area 
required. One element of the integer array is equivalent to one word of memory. 

If the heap is used by a function before init .heap has been called the C memory 
allocation functions will fail with their normal error returns. 

PROC terminate. heap. use (VAL INT GSB) 

terminate . heap . use should be called when the heap is no longer required, I.e. 
when no more C functions will be called. It provides a clean way of terminating the 
use of the heap. 

Once the heap terminate procedure has been called, the state of the heap is unde- 
fined. 

terminate. heap. use must be called before terminating the static area 
because the heap is accessed using static variables. 



72 TDS 366 01 March 1993 



11 Mixed language programming 217 



FROC terminate . static . use (VAL INT GSB) 

terminate. static. use Should be called when the static area is no longer 
required, i.e. when no further calls to C will be made. Jt provides a clean way of 
ending the use of the C static area. 

Once the static temiinate procedure has been called, the state of the static area 
is undefined. 

Example 

The following example illustrates how these library procedures can be used to set 
up and temiinate the static and heap areas for a C function. The C function to be 
called is: 

#ijiclude <stdlib.h> 

int c_fiincUnt n, int release) { 

static int *ptx = NULL; 
int i; 

if (ptr = MOLL) ( 

ptr ^ (int *) inalloc{n); 

if (ptr = NDLL) 
return 1; 
\ 

for (i ^ 0; i < n / sizeof (int) ,- i-H-) 
ptrli] = x; 

if (release) ( 

free (ptr) ,* 

ptr = NULL; 
) 

return 0; 
) 
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The Occam code to call this function (on a 32 bit transputer) is shown below: 

lINCLODE ''hostio.inc" 

#USE "hostio,lib" 

#USE ''calXc.lib" — the 'calling C functions, 

#PRAGMR TRANSLATE C "c_func" 

— declare the C function as an occam descriptor. 

#PRaa4a external "INT FDNCTION C{VAL INT GSB,x,frad) = 200" 

PROC mixed (CHAN OF SP fs, ts, []INT freemem) 
INT GSBr required . size : 

' — Allow very large static and heap area sizes 
VAL static. size IS 4000 : 
VAL heap. size IS 4000 : 

[static, sizej INT static. area : 

[heap. size] INT heap. area : 

SEQ 

— set up static, area as the static area 
init. static (static. area r required. size, GSB) 

— now check for error 
IF 

required. size > static. size 

so .write . string (fs , ts , 

"error initialising static*n'') 
TRUE 

INT fail: 

SEQ 

— Set up the heap area. 

— Note that GSB is the first parameter 
init. heap (GSB, heap. area) 

— Call the C function. Note that the GSB 

— is passed as the first parameter. 
fail :- C (GSB, 20000, 0) 

IF 

fail = 

so. write. string (fs, ta, "malice OK*n") 
TRUE 

so. write. string (fs, ts, "malloc failed*n") 

— now tidy up the stack iuid heap allocated 
terminate . heap . use (GSB) 

terminate .static . use (GSB) 

— and exit 

so.exit(fs, ts, sps. success) 



The Occam program must be compiled and then linked with the compiled C func- 
tion, the memory allocation library, the reduced C runtime library, the occam host 
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i/o library^ and the standard occam libraries. In this example (assuming that the 
C source code is in a file called cfunc. c and the ocxam source is In a file called 
mixed . occ) the set of files to be linked is: 

mixed, tco compiled Occam program 

cfunc . tco compiled C function 

clibsrd^lnfc linker indirect file for the C reduced runtime library 

hostio . lib Occam i/o library 

callc , lib call C library 

occama. Ink linker indirect file listing standard Occam libraries for code 
compiled for transputer class TA 

Sources can be found on the toolset examples directory. Standard libraries and 
linker indirect files are available on the toolset libraries directory. 

The linker allows files to either be specified on the command line or listed In an indi- 
rect file. Because there are several files required in this instance, it may be easier 
to supply a linker indirect file. This file can also include a #mainentry directive 
to define the entry point of the program, in this case the top level occann procedure 
'"mixed". To do this create a text file called callc. Ink, containing the following 
lines: 

mixed . tco 

cfunc . tco 

#include clibsrd.lnk 

hostio -lib 

callc. lib 

#include occaraa.lnk 

#mainentry mixed 

The con-ed linker command line (using the default processor T414 in HALT mode) 
would be as follows: 

ilink -f callc. Ink (UNIX) 

ilink /f callc. Ink (MS-DOSA/MS) 

Details of the operation of the linker can be found in chapter 9 in the Tcfolset Refer- 
ence Manual, 

Once linked, the program can be collected and mn in the usual way. The output 
of the program is the message 'malloc OK'. 
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11.1.9 Restrictions and caveats 

General 

A number of restrictions must be observed when calling routines written in one 
language from a program in a different language: 

1 The formal and actual parameters {and function return types) must be 
compatibte. See sections 11.1.3 and 11.1.5 for more detail. 

2 As Occam does not have 'external* variables, there can be no common 
data between the calling program and the called routine. Therefore, the 
only way that data can be transferred between them is by means of param- 
eters (and return values). The called procedure may also use channels to 
communicate with other paris of the program that are running in parallel. 

3 No function or procedure which requires direct communication with the 
host file server may be called. 

Rules for importing C code 

The following restrictions apply to C functions which are to be called from an 
Occam program: 

1 Stack checking should not be enabled in any C function to be called from 
Occam. 

2 Only C functions linked with the reduced C runtime library, can be called 
from Occam, i.e. those which do not require any server communication. 

3 ImporledCfunctionswhich return a singlevalue(otherthan a pointer) must 
not have any 'side-effects'. They must not: alter parameters and variables 
(except those dedared within the function); perform channel or host i/o; call 
functions which do have side-effects; perform parallel operations; use 
timer delays; or perform heap operations. 

4 The following functions cannot be called in the imported C code: 

clock 

exitO 

exit_tenninatd 

exit_no terminate () 

exit_repeat() 

getjdetail_of__f ree_stack_space { ) 

72 TDS 366 01 March 1993 



11 Mixed language programming 221^ 

Rufes for importing occam code 

There are certain rules which govem the calling of Occam code from C: 

1 Occam functions that return more than a single value may not be called. 

2 The Occam procedure or function to be called must be at the outer level 
of a compiled module. 

3 INLINE procedures and functions cannot be called from C. 

4 The Occam code must not use vector space, or call any other occam 
code which uses vector space. Arrays, if used, should be explicitly placed 
within workspace or the code should be compiled with the v option to 
disable the use of separate vector space. 

Some Occam libraries supplied with the occam 2 toolset use vector 
space and therefore cannot be called from C. These are: 

hostio.lib streamio.lib msdos.lib 

5 There must be enough workspace for the calfed procedures or functions 
on the stack of the calling program. It Is the programmer's responsibility to 
ensure that this is the case. 

6 There must be no aliasing between the parameters to occam functions or 
procedures and the destination of the result In other words the same vari- 
able must not be used as both a parameter which will be read, and as a 
result. The Occam compiler checks that this is so for Occam procedures 
and functions called wthin an occam program. 

The presence or absence of alias checking when the OCCam code is 
compiled has no effect on this mie. 

As an example consider the occam function; 

INT FDNCTION succ {VAL INT n) IS n + 1 : 

If this is called from within an OCCam program, the compiler will check to 
see whether the parameter and result are aliased; if they are then the 
compiler v^rill generate temporary variables as necessary. So, for example, 
the Occam call i := succ{i) may be complied with a temporary vari- 
able for the ftjnction result, which is then copied to the variable i. The C 
compiler Is not able to perform these checks and so, If this function is called 
from C, it is up to the programmer to ensure that there is no aliasing. A suit- 
able calling sequence could be: 

iii't tiap ; 

tmp = succ(i) ; 
i = tnip; 

Note that there may be mutual aliasing between Val parameters as these 
are only read, not written. 
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11.2 Occam Interface procedures 

The following sections describe a set of interfaces provided to allow complete 
programs written in C to be called from Occam. This might be done for various 
reasons, for example to allow a C program to be used with the occam configurer 
occonf , or to provide some simple modification of the runtime environment of the 
program — e.g. initializing some external hardware before the application code 
starts, or intensepting the program's communications with the host file server. 

By specifying the appropriate entry point fora C program, it is given an occam-like 
procedural interface allowing the program to be called from an occam program, 
The code produced in this way is known as an Occam equivalent process as it 
makes the program look like an occam process with channels for inputand output. 



11.2.1 Interface code 

The occam interface code described here provides a number of fixed interfaces 
to a C program. There are three types of interface code, known as types 1 , 2, and 
3. Descriptions and process diagrams for the three interfaces are given below. 

Typel 

This interface is used when the C program runs on a single transputer and commu- 
nicates only with the host file server. This interface is used with the full version of 
the C runtime library. 




Figure 11.1 Type 1 interface 

Type 2 

This interi'ace is used when the C program communicates with other processes as 
well as the host file server. This interface is used with the full version of the C 
runtime library. 
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Figure 11.2 Type 2 interface 

Type 3 

This interface is similar to the type 2 interface except that there is no access to the 
host file server. The interface must be used with the reduced version of the C 
runtime library, which does not contain any functions which require access to 
iserver facilities such as the host file system. 
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Figure 11 .3 Type 3 interface 

Channel arrays 

The Type 2 and type 3 interfaces have arrays of channels which enable the C 
program to communicate with other processes in the program. These arrays are 
mapped directly onto the channel arrays which form part of the standard parameter 
list of the C main function (see section 11.27). 

These channel an-ays actually appear as an-ays of integers in the occam param- 
eter lists — this allows pointers to channels to be passed to the C program which 
provides a more flexible way of mapping channels onto the an-ays. Because 
Occam does not support pointers directly, two library procedures are provided to 
assign channel pointers to array elements (for more Information on these, see the 
examples below and the occam 2 Toolset Language and Llbranes Reference 
Manual). 
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Reserved channels 

Two of the input channels and two of the output channels in the Type 2 and Type 
3 Occam interface procedures (i.e, in[0], in[l], out[0] and out[l]} are 
reserved. No program should use these channels. They are reserved as follows: 

out [ ] Reserved for diagnostic output. 

in [0] Reserved for diagnostic input. 

outEl] Messages from the mntime library to the host file server. 

in [1] Responses from the host file server to the runtime library. 

11.2.2 Parameters to the C program 

Parameters to the C main function are described by the following function proto- 
type: 

#include <c:hanndl.h> 

int main (inb argc, char *argv[], char *envp[], 
Channel *in[], int inlen, 
Channel *out[] ^ int outlen) ; 

Where: 

• argc — the number of arguments passed to the program from the 
command line, including the program name. 

• argv — an an^ay of pointers to those arguments. 

Note: for programs linked with the reduced mntime library (i.e. using the 
Type 3 interface), argc is set to 1 and the first element of argv is a pointer 
to an empty string. 

• envp — included for compatibility with previous toolsets — In this imple- 
mentation, this parameter is always set to null. 

• in — an array of input channels. 

• inlen — the size of the array in. 

• out — an array of output channels. 

• outlen — the size of the an'ay out. 

The channel an^ys in and out in the C program are passed from the interface 
procedures, and can be set up as described below. Where applicable, these chan- 
nels can be used by the C code to communicate via channels passed in from the 
calling Occam program. Note, however, that the first two elements in the an-ays 
are reserved for use by the C program's runtime system and cannot be used by 
the application program. 
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11,2.3 Stack and heap requirements 

Data storage (workspace) requirements for C programs are provided by arrays in 
the Occam code. Stack, static and heap requirements vary from program to 
program. The workspace arrays passed to the program must be large enough to 
accommodate: 

• the stack needed by the program when it runs 

• all the static data required by the program 

• the heap used by the program and the runtime libraries. 

Stack overflow may lead to unpredictable behavior by the program. For this reason 
it is best to run a program initially with a large combined stack and heap. Later, after 
the program has been run to detemnine stack and heap usage, it can be modified 
to use a separate stack and heap of the appropriate sizes. The use of a separate 
array forthe stack allows the stack to be placed in the transputer's internal memory 
to optimize the performance of the program. Methods for optimizing memory 
usage are described in: Performance Improvement with the INMOS Dx305 
Occam 2 Toolset (supplied with the toolset); and INMOS Technical Note 55 Using 
the Occam toolsets with non-occam applications. 

A minimum stack size of 512 words is recommended. 

Stack overflow detection 

Failure or unpredictable behavior of programs may be due to stack overflow. To 
obtain an estimate of the amount of stack used by a program: 

1 Build all C code with stack checking enabled. 

2 Call the function max_stack_usage at the end of the program, this will 
return an approximation of the amount of stack used by the program. 

A test for stack overflow in a program is to use the procedure outlined below: 

1 Initialize the bottom few words of the stack (a falling stack is used) to some 
easily recognizable pattem of values. 

2 Run the program and, after it crashes, use the debugger to examine the 
values in the stack. If the values you initialized have been changed then 
stack overflow is likely. 

3 Increasethestacksizeand try again. 

A similar method can be used to detennine static data and heap requirements, 
except that these are allocated upwards in memory. The following OCCam frag- 
ment gives an example of Initializing the bottom of the stack: 

SEQ i = FOR SIZE wsl 
wsl[x] := #DEFACED 
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Stack overflow in the C parts of the program can also be detected by using the 
stack checking mechanism buiit into the C compiler and libraries. 

11.2.4 Type 1 interface definition 

The Type 1 interface is used when the C program does not communicate with any 
other process apart from the host file server. 

The parameters for the Type 1 procedure are; a pair of channels to communicate 
with the host file server; and two arrays to provide the C program's heap, static and 
stack space. 

Procedural interface 

The Type 1 OCCam interface is defined as follows: 

PROC MAIN. ENTRY (CHAN OF SP fs, ta, 
[]INT free. memory, 
[]INT stack. memory) 

The parameters to this procedure are: 

• f s — a channel from the host file server to the C program. 

• ts — a channel from the C program to the host file server. 

The channels fs and ts are connected to the channels in[l] and 
out [1] which are passed as parameters to the C program — these are 
provided for the use of the C runtime Nbraries only, and should not be used 
by the application code. 

• free . memory — used by the C program for Its heap and static areas. 

This array is generally used to pass the free memory which is available to 
the C program after the all the code has been loaded. 

• stack , memory — used by the C program for its runtime stack (if the size 
of the an-ay is non-zero). 

If the size of the stack, memory an^y is zero then the free. memory 
array is used for the program's runtime stack as well as for the static and 
heap data areas. 

Parameters to C program 

The channel an^y parameters to the C main function are set up as follows: 

• inlen and outlen are set to 2 

• in [0] and out [0] are set to NULL 
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• in [1] is a pointer to the f s channel and is used by the C runtime system 
to communicate with the host 

• out[l] isapointertothe tschannelandisused bytheCmntimesystem 
to communicate with the host 

Example 

The following example is an Occam procedure, call,progl, which calls a C 
program via the MfliN. ENTRY procedure interface: 

#INCLUDE ^'hostio.inc" 

PROC call,progl (CHAN OF SP fs, ts) 

#USE "centry.lib" — C interface code 

[100000] INT heap : — static and heap space 

[1024] INT stack : — stack for program 
PLACE stack IN WORKSPACE : -- Put on chip 

— call program 

MAIN. ENTRY (fs, ts , heap, stack) 

11.2.5 Type 2 Interface definition 

The Type 2 interface is used when building a program that will communicate with 
other processes as well as with the host file server 

The parameters for the Type 2 procedure are: a pair of channels to communicate 
with the host file server; a flag value to control the use of memory by the C program; 
two arrays to provide the C program's heap, static and stack space; and a pair of 
channels for passing channel pointers to the C program. 

Procedural interface 

The Type 2 Occam interface is defined as follows: 

PROC PROC. ENTRY (CHAN OF SP fs, ts , 
VAL INT flag, 
[]INT wsl, ws2, 
[]INT in, out) 

The parameters are described below: 

• f s — a channel trom the host file server to the C program. 

• ts — a channel from the program to the host file server 

The channels fs and ts are connected to the channels in[l] and 
out [1] which are passed as parameters to the C program — these are 
provided for the use of the C runtime libraries only, and should not be used 
by the application code. 
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• flag — indicates whether one or two workspaces are to be used. 

If the value of flag is set to then the program will run with two wori<space 
areas; one for static and heap data, the other for the runtime stack. If the 
value of flag Is set to 1 then the program will run with a single combined 
workspace. 

• wsl — used by the C program for its wofkspace. 

If flag is then this an^ay is used only for the runtime stack, if flag is 1 
then ft is used as the program's combined workspace (static, heap and 
stack). 

• ws2 — used by the C program as its static/heap workspace when flag is 
set to zero, otherwise unused. 

• in — an array of pointers to Occam channels going to the C program. 

• out — an an^y of pointers to Occam channels going from the C program. 

Note: The first two eleme nts in the channel pointer arrays in and ou t are reserved 
for use by the C program's runtime system and cannot be used by the program. 

Parameters to C program 

The channel array parameters to the C main function are set up as follows: 

• inlen and outlen are setto the number of elements in the Occam arrays 
in and out 

• in[0] and out [0] are set to NULL 

• in [1] is a pointer to the ts channel and is used by the C runtime system 
to communicate with the host 

• out[lI is a pointertothets channel and is used bytheC runtime system 
to communicate with the host 

• The remaining elements of the an^ys in and out are set to the values in 
the corresponding elements of the Occam arrays 
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Example 

The following example is an occam procedure, call.prog2, which calls a C 
program via the PROC . ENTRY procedure interface: 

#INCHn)E "hostio.inc" 

PROC call,prog2 (CHAN OF SP fs, ts, 

CHAN OF COMM to. process, 
CH2^ OF COHH from. process) 

#USE "hostio.lib" 

#DSE "Gentry. lib" — C interface code 

VAL flag IS 1 : — combined heap and stack 

[100000] INT wsl : — stack and heap for program 

[1]INT ws2 ; — dummy workspace for program 

[3] INT in, out : — channel pointers (not used) 

SEQ 

— set up user output channel 

LOAD, OITTPUT. CHANNEL (out [2] , from. process) 

— set up user input channel 

LOAD, INPUT. CHANNEL (in [2 ] , to. process) 

— call program 

PROC. ENTRY (fs, ts, flag, wsl, ws2, in, out) 
so.exit (fs, ts, sps. success) 



Two channels are declared of type COMm, the first being an input channel to the 
process, the second an output channel from the process. (The declaration of 
protocol type COMM is assumed.) 

11.2.6 Type 3 Interface definition 

The Type 3 interface is used to run programs which communicate with other 
processes on the same processor or in a network of processes, but which do not 
require access to host services. Processes built with the Type 3 interface can 
communicate with other processes through channels in the same way as Type 2 
processes. 

Programs using the Type 3 interface must be linked with the reduced C runtime 
library. 

The parameters for the Type 3 procedure are: a flag value to control the use of 
memory by the C program; two arrays to provide the C program's heap, static and 
stack space; and a pair of channels for passing channel pointers to the C program. 
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Procedural Interface 

The interface for Type 3 equivalent Occam processes is defined beiow: 

PROC PROG, ENTRY. RC (VAL INT flag, 

[]INT wal, ws2, 
[]IKT in, out) 

The parameters are described in the following list 

• flag — indicates whether one or two wori<spaces are to be used. 

If the val ue of flag is set to then the program will run with two workspace 
areas; one for static and heap data, the other for the runtime stack. If the 
value of flag is set to 1 then the program will run with a single combined 
wori<space. 

• wsl — used by the C program for its workspace. 

If flag is then this array is used only for the runtime stack, if flag \s 1 
then it is used as the program's combined workspace (static, heap and 
stack), 

• ws2 — used by the C program as its static/heap workspace when flag is 
set to zepD, otherwise unused. 

• in — an array of pointers to Occam channels going to the process. 

• out — an array of pointers to Occam channels coming from the process. 

Note: The first two elements in the channel pointer arrays in and out are reserved 
for use by the C program's runtime system and cannot be used by the Occam 
program. 

Parameters to C program 

The channel an^y parameters to the C main function are set up as follows: 

• inlen and outlen are set to the number of elements in the Occam an^ays 
in and out 

• in[0], in[l], out[0] and out[l] are are set to NULL 

• The remaining elements of the an'ays in and out are set to the values in 
the corresponding elements of the Occam an^ays 
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Example 

The following shows how to call a Type 3 equivalent occam process from occam 
source, and how to set up the parameters required. The example consists of an 
Occam procedure 'call .prog3' within which a C program is called. 

PROC call.prog3 (CHAN OF COMM to. process^ 

CHAN OF COMH from. process) 

#USE "centry.lib" — C entry point library 

VAL flag IS - — separate heap and stack 

[1000] INT wsl : — stack for program 

[40000] INT W32 ; — heap for program 

[3] INT in, out : — pointers to inputs/outputs 

SEQ 

— set up user output channel 

LOAB. OUTPUT. CHANNEL {out [2], from. process) 

— set up user input channel 
L0AD,INPUT.CHANNEL(in[2] , to. process) 

— call program 
PRDC.ENTRy.RC(flag, wsl, Ws2 , in, out) 



Two channels are declared of type COMM, the first being an input channel to the 
process, the second an output channel from the process. (The declaration of 
protocol type COMM is assumed.) 

The first statement sets up a pointer to the output channel, using the procedure 
LOAD. OUTPUT. CHANNEL. The second statement sets up a pointer to the input 
channel, using the procedure LOAD . INPUT . CHANNEL. Note thatthe first two input 
and output channels are reserved by the runtime system even though there is no 
host communication taking place. 



11.2.7 Building the OCCam equivalent process 

The Occam equivalent processes built from these interfaces can be called from 
an Occam program in the same way as any other oCcam procedure. Note that, 
because the interface procedures have fixed names, there can only be one 
process of a particular type in each linked unit. However, multiple C programs 
called in this way may be placed on a processor by the configurer. 

Once all the component C and Occam code for the complete program has been 
compiled, it is linked with the C runtime libraries, the occam entry points library 



72TDS366 01 March 1993 



232 __^ 11.2 Occam interface procedures 

and any other occam libraries required. The program is then configured and a 
bootable code file produced. 

The Occam interface code is supplied in the library centry . lib. The C libraries 
can be linked by using the linker control file clibs . Ink, for the full runtime library, 
or clibsrd.lnJc, for the reduced njntime library. For example, consider a 
program that consists of the following compiled fifes: 

• main , tco — the compiled C program to be called from Occam 

• wrap , tco — the compiled Occam code that calls the interface procedure 

This program can be linked with the full run-time libraries, for a 32 bit transputer, 
using the following command; 

ilink wrap. tco main. tco cailc.lib -f clibs. Ink -f occama.lnk 

(UNIX toolsets) 

ilink wrap. tco main. tco cailc.lib /f clibs. Ink /f occama.lnk 

{MS-DOSA/MS toolsets) 
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INMOS EPROM software is designed so that programs can be developed, booted 
onto a network via iinl< and tested using the INMOS toolset. Once they are working, 
they can be placed in ROM with only minor change. 

12.1 Introduction 

During development, software is booted onto a network from a link connecting the 
network to the host computer. Then the software is prepared for a ROM, which is 
attached to the root transputer in the network. 

Figure 12.1 shows how a network of five transputers would be loaded from a ROM 
accessed by the root transputer. 
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Figure 12,1 Loading a network from ROM 

To prepare software to be booted from ROM, rather than to be booted from link, 
the following two steps must be taken: 

1. Give different options to the configurer and collector tools so that they 
produce ROM-bootable code. 

2. Run the ieprom tool to produce a file or set of files suitable for blowing into 
EPROM. 

Figures 12.2 and 12.3 illustrate the stages of preparing ROM-bootabfe software. 

Figure 12.2 shows an Occam program compiled and linked for a single processor. 
Figure 12.3 shows a configured program, consisting of one or more linked units, 
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12.2 Processing configurations^ 



connected together and allocated to processors as described in a configuration 
fife. 
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Figure 12.2 Preparation of ROM-bootable software (single occam program) 
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Figure 12.3 Preparation of ROM-bootable software (configured program) 

12,2 Processing configurations 

The processing configuration used will depend on the number of software 
processes, the number of transputers availatile to mn the code and whether the 
code is to run from ROM or RAM. The following sections outline the possible 
configurations. 

When preparing FORTRAN or C code to be booted from ROM the configurer must 
be used in order to s pecify the size of stack and heap. Th is applies even when the 
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application consists of a single process running on a single processor A single 
Occam process can be configured or prepared as a single, linked program. 

12.2.1 Single processor, run from ROM 

The application process is prepared as one or more processes, connected as 
described in a configuration file. If the application consists of a single Occam 
program then it can be prepared without using the configurer. It is then run on a 
single processor, wth the code in ROM, and the RAM is used as the data area. 

12.Z2 Single processor, run from RAIW 

The application process is prepared as one or more processes, connected as 
descrit>ed In a configuration file. If the application consists of a single Occam 
program then it can be compiled and iinked without using the configurer. When 
booted from ROM, the processor copies the code into RAM and runs it, using the 
RAM for the data area. 

12.2.3 Multiple process, multiple processor, run from RAM 

The application is prepared as a collection of processes, connected and allocated 
to pnjcessors as described in a configuration fiie. The compiled and configured 
application code is placed in the ROM of the root processor. When booted from 
ROM, the root pnDcessor loads its own code into RAM, and loads the rest of the 
network via its links. Each processor then sets off its own processes, and the 
application mns, (This is the configuration shown in figure 12.1). 

12.2.4 Multiple process^ multiple processor, root run from ROM, rest of 
network run from RAM 

The application is prepared as a collection of processes, connected and allocated 
to processors as described in a configuration file. The compiled and configured 
applicafion code is placed in the ROM of the root processor When booted from 
ROM, the root processor loads the rest of the network via its links, and then 
continues to run its own code ft-om the ROM. 

12.3 The EPROM tool: ieprom 

The EPROM tool ieprom takes the output of the collector, and produces a file or 
set of files suitable for blowing into an EPROM. The following output formats are 

supported: 

- Binary 

- Hex 

- Intel hex format 

- Intel extended hex format 

- Motorola S-record format 
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ieprom supports the production of code files In blockmode , wfiich allows the code 
to be placed In a set of different files. This is useful to program EPROMS organized 
as separate byte-wide devices, or where the EPROM programming device does 
not have enough memory to hold the entire image, 

ieprom also supports the inclusion in the EPROM image of a memory configura- 
Hon, Some 32-bit transputers have a configurable memory interface which can be 
initialized from a fixed area in the ROM, when the transputer is reset, A particular 
memory configuration can be specified to ieprom in a text file. These files are 
known as memory configuration files and normally have the file extension .mem. 
The format of these files, and the facility to edit them using an interactive tool called 
iemit is described in chapter 6 of the accompanying Toolset Reference Manual. 

ieprom is driven by a control file which normally has the file extension ,epr. A 
detailed description of ieprom and its control file is given in chapter 7 of the accom- 
panying Toolset Reference Manual. 



12.4 Using the configurer and collector to produce ROM-boot- 
able code 

To produce code suitable for running in ROM or RAM, the configurer and collector 
loofs must be specified with the appropriate command line options. The following 
options are used to configurer single and multi-processor programs and to collect 
unconfigured single processor programs: 

• The ro option specifies that the code is to run in ROM. 

• The ra option specifies that the code is to mn in RAM. 

• The rs option specifies the ROM size (if not specified in configuration file). 
This option does not apply to the occam configurer occonf , see below. 

In addition, if using icconf (the C configurer), the p option must be used in order 
to specify the root processor name. 

If using occonf , the NETWORK description in the configuration file should indicate: 

• which processor is the root processor, by setting its root attribute to true 

• the size of the ROM on that processor, by setting its romsize attribute to 
the appropriate value, in bytes. 

The collector will add the appropriate ROM bootstrap to the application code and 
the output file will be given the extension .btr. 
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12-5 Summary of EPROM tool steps for different configurations 



12.5.1 Using icconf 
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12.5.2 Single processor unconfigured Occam program 
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12.5 Summary of EPROM tool steps for different configurations 



12.5.3 Using occonf 
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This chapter describes a number of features of the toolset OCCam 2 compiler 
which support low-level programming of transputers. These are as follows: 

Allocation This allows a channel, a variable, an array or a port to be placed at an 
absolute location in memory. 

RETYPING channels and creating channel an-ay constructors. These facilities 
enable channels to be manipulated. 

Code insertion This allows sections of transputer machine code to be inserted into 
occann programs. 

Dynamic code loading A set of library procedures is provided that allows an 
Occam program to read in a section of compiled code {from a file, for 
example) and execute it. 

Extraordinary use of links A set of library procedures is provided which allow link 
communications which have not completed to be handled by timeout, or be 
aborted by another part of the program. 

Scheduling Using the predefined routine reschedule to reschedule processes. 

Setting the error flag The transputer error flag can be explicitly set using the 
predefined routine CAUSEerror. 



13,1 Allocation 

Allocation is perfomied using the occam PLACE statement, which is defined 
formally as follows; 

allocation = PLACE name AT expression : 

(Section A.3.2 of the Occam 2 Toolset Language and Libraries Reference Manual 
provides details of the PLACE statement). 

The PLACE statement allows a variable to be assigned to a specific memory loca- 
tion. The variable can be a scalar variable, array variable, channel, or port. This 
feature may be used for a number of purposes, for example: 

• To map Occam channels onto specific transputer links from within an 
occann program. Channels mapped onto links in this way are known as 
'hard' channels. 
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• To map arrays onto particular hardware such as video RAM. 

* To access devices (such as UARTs or latches) mapped into the transput- 
er's address space. 

The PLACE statement must be inserted immediately following the declaration of 
the variable to which it refers e.g. 

int Xf Yf z ; 

PLACE X . 

PLACE y is correct 

int X : 
int y : 
PLACE X is incorrect 



13.1.1 The PLACE statemertt 

Normally the PLACE statement should not be used to force critical arrays or vari- 
ables into on-chip RAM. The Occam compiler allocates memory according to the 
scheme outlined in Appendix B of the Occam 2 Toolset Language and Ubranes 
Reference Manual, and cannot allow data to be placed arbitrarily in memory. To 
make the best use of on-chip RAM use separate vector space as described In 
section 5.6. 

The address of a placed object is derived by treating the value of the expression 
as a word olTset into memory. In Occam addresses start at zero, while physical 
machine addresses start atMOSTNEG int (#80000000 on 32-bit transputers and 
#8000 on 16-bit transputers}. An Occam address can be considered as a 
subscript to an INT vector mapped onto memory. Thus the following statement 
would cause chan to be allocated address #80000004 on a 32-bJt transputer: 

PLACE Chan AT 1: 

Addresses are calculated in this way so that the transputer links can be accessed 
using code that is independent of the word length. The links are mapped to 
addresses 0, l, 2.. .7. (See section 13.1.3). 

Translation from a machine address to the equivalent occam address place 
value can be achieved by the following declaration: 

VAL Occam. addr IS 

(machine . addrX (MOSTNEG INT)) » w, adjust: 

where: w. adjust is Ifora 16-bit transputer and 2 for a 32-bit transputer. 

All placed objects must be word aligned. If it is necessary to access a byte object 
on an arbitrary boundary, or an INT16 object on an arbitrary 1 6-bit boundaryj the 
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object must be an element of an array which is placed on a word address below 
the required address. For example, to access a BYTE port called io. register 
located 3t physical address #40000001 on a 32-blt transputer use the following: 

[4] PORT OF BYTE io.regs.vec : 
PLACE io.regs.vec AT #30000000 : 
reregister IS io.regs.vecEl] : 

The PLACE statement must be placed immediately after the declaration of the vari- 
able. 

Placement may be used on transputer boards to access board control functions 
mapped into the transputer's address space. For example, on a TRAM with a 
subsystem, the subsystem control functions (Error, Reset and Analyse) are 
mapped into the address space and can be accessed from Occam as placed 
ports. The following code will reset the subsystem on a TRAM: 



PROC reset. tram. subsystem () 



— address 

— address 

— address 4 



VAL subsys. reset IS #20000000 
VAL subsys. error IS #20000000 
VAL subsys . analyse IS #20000001 
PORT OF BYTE reset, amalyse, error: 
PLACE reset AT subsys. reset: 
PLACE analyse AT stibsys . analyse : 
PLACE error AT subsys . error : 
VAL delay IS 78: — 5 msec delay 
TIMER clock: 
INT time: 
SEQ 

— set reset and analyse low 

analyse I (BYTE) 

reset ! (BYTE) 

reset ! 1 (BYTE) — hold reset high 

clock ? time 

clock ? AFTER time PLOS delay 

reset ! (BYTE) — reset subsystem 

The Error and Analyse functions can be controlled from occam in a similar way. 

A more specific example of how to reset B004 type boards is given in the examples 
directory exaii^les/manuals/assert. 

13.1.2 Allocating specific workspace locations 

A number of specialized transputer instructions require specific wori<space plac- 
Ings. For example, the instructions postbormsn, outbyte, outword and the 
disabling ALT instructions all use workspace location 0. To accommodate this the 
compiler supports the following allocation: 

PLACE name AT WORKSPACE n: 
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where: nis a constant mteger. (See Appendix A in the OCcam 2 Toolset Language 
and Libr^nes Reference Manuallor syntax details). 

This is used to ensure that a variaWe is allocated a particular position within a 
procedure or function's workspace. The compiler ensures that at least n words of 
workspace are allocated, and that no other variables are placed at that address. 
The compiler will warn if a variable PLACED AT workspace n is in scope when 
its own workspace allocation requires to use that workspace location, or when 
another is placed at the same location. 

For example on a T425, the POSTNORMSN instruction can be used to pack a floating 
point number; It requires an exponent to be previously stored at workspace offset 
0. The following code may be used: 

REAL32 FDKCTION pack (VAL INT guard, frac, exp, sign) 
REAL32 result : 
VALOF 

INT temp : 

PLACE temp AT WORKSPACE : 

SEQ 

temp := exp 
ASM 

LDAB guard, frac 
NORM 

POSTNORMSN 
ROUNDSN 
LDL sign 
OR 

ST result 
RESULT result 



(For the background on this example, see the Transputer instruction set -a 
compiler writer's guide, section 7.1 1 .2). Use of the asm construct is described in 
sectfon 13.3. 



13.1.3 Allocating channels to links 

When mapping channels to specific transputer links, the channel word is placed 
at the specified address for scalar channels. Arrays of channels, however, are 
mapped as arrays of pointers to channels: 

PLACE scalar. channel AT n: 
places the channel word at that address. 

PLACE array .of .channels AT n: 
places the an'ay of pointers at that address. 

The following two code fragments illustrate the placement of channels on links. 
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CHAN OF ANY in.linkO, out.linkO 
PLACE in.linkO AT linkO.in: 
PLACE out.linkO AT linkO.out: 

CHAH OF ANY in.linkl, out.linkl 
PLACE in.linkl AT linkl.in: 
PLACE out.linkl AT linkl.out: 

CHAN OP ANY in,link2, out.link2 
PLACE in.link2 AT link2.iii: 
PLACE out.lin3c2 AT link2.out: 

CHAN OF ANY in.link3, out.link3 
PLACE in. links AT link3.in: 
PLACE out. links AT link3.out: 

CHAN OF ANY in. event : 
PLACE in. event AT event. in: 



or: 



CHAN OF ANY out.linkO, out.linkl, out.link2, out.link3 : 
PLACE out.linkO AT linkO.out : 
PLACE out.linkl AT linkl.out : 
PLACE out.link2 AT link2.out : 
PLACE out.link3 AT linkS.out : 

[4]CHAN OF ANY outlink IS [out.linkO, out.linkl, 

out.linlc2, out.link3] : 

CHAN OF ANY in.linkO, in.linkl, in.link2, in.linfc3 : 
PLACE in.linkO AT linkO.in : 
PLACE in.linkl AT linkl.in : 
PLACE in.link2 AT link2.in : 
PLACE in. links AT linkS.in : 

[4]CHAN OF ANY inlxnk IS [in.linkO, in.linkl, in.link2, 
in.linkS] : 

Link addresses are defined in the include file linJcaddr , inc that is supplied with 
the toolset. 

Although shown here as chan of any channels you should use specific occam 
channel protocols wherever possible to ensure that channels are properly checked 
at compile time. 

13.2 RETYPING channels and creating channel array construc- 
tors 

Channels may be RETYPEd, (see also section A.2.1. of the Occam 2 Toolset 
Language and Ubraries Reference Manual}. This allows the user to change the 
protocol on a channel in order to pass it as a parameter to another routine, for 
example: 
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PROTOCOL K^0T32 IS 1NT32 : 
PROC p {CHAN OF INT32 X} 
X ! 99{INT32) 

PROC ql (CHAN OF PROT32 y) 
SEQ 

p {y) — this is illegal 
CHAN OF INT32 z RETYPES y : 
p(z) — this is legal 



The facilities for RETYPEing channels should only be used by programmers who 
understand the implementation of transputer channels, and the implications of 
attempting to circumvent Occam's checking of channel usage. These facilities 
may be useful for those programmers who are using Occam at a very low level, 
for example, writing loaders and other operating system type functions. 

The current implementation of channels allows flexible use of channel an^ys, 
which are implemented as an array of pointers to channel words. This means, for 
example, that it is possible to create an array of channeis which map onto the hard 
links in a different order than to 3, by using channel an"ay constructors. For 
example: 

CHAN OF ANY out.linkO, out.linkl, out.link2, 

out . Iiiik3 : 

PLACE out.linJcO AT linkO.out : 

PLACE out.linkl AT linJcl.out : 

PLACE out.linlc2 AT link2.out : 

PLACE out. links AT linkS.out : 

[4]CHAN OF ANY outlink IS [out.link3, out.linkl, 

out . Iink2 , out . linkO ] ; 

A particular effect of this implementation is that It may be useful to retype channels 
and arays of channels into integers, in order to give the programmer access to 
these pointers. A programmer may set up an array of integers whose values are 
the addresses of channel words, and then use these as addresses of channels, 
like so: 



[n]INT x: 
SEQ 

. . . initialize elements of array x, then: 

[nlCHAN OF protocol c RETYPES x: 
SEQ 

. . . 1:hen communicate on cli] 
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Pseudo-operations are more complex operations built up from sequences of 
instructions. Like macros, they expand into one or more transputer instructions, 
depending on their context and parameters. 

For example, to perform a 1*s complement addition we can write the following 
occann: 

INT carry, temp: 
SEQ 

carry, temp := LONGSUM (a, b^ 0} 

G := carry PLUS temp 

However, if this occurs in a time-critical section of the program we might replace 
it with: 

ASM 

LDABC a, b^ 

LSXJM 

SDM 

ST c 

which would avoid the storing and reloading of carry and ten^, (Note: such 
examples are specific to the cun-ent compiler implementation; future releases are 
likely to behave differently). 

Values in the range mostneg INT to MOSTPOS INT may be used as operands 
to all of the direct functions without explicit use of prefix and negative prefix instruc- 
tions. Access to non-Jocal Occam symbols is provided without explicit indirection, 
if you use the pseudo-instructions 'ld', 'ij>ab' etc. 

A more complex example, which sets an enx)r if a value read from a channel is not 
in a particular range, takes advantage of both these facilities: 

INT a : 

other code 
PROC get. and. check. index {CHAN OF INT c) 
SEQ 
c ? a 
ASM 

LDAB 512, a — push value of free 

— variable onto stack 

— followed by 512 
CCNTl — if NOT {0 < a <= 512) 

— then set error 



Ifthereisa requirement for the code insertion to use some work space, then the 
work space may be declared before the ASM construct, in which case, the work 
space locations are accessed like any other Occam symbol. 



72TDS366 01 March 1993 



248 13.6 Scheduling 



INT a 


; 


SEQ 




INT 


b, c : 


ASM 




LD 


a — 


ST 


b 


. . . 


more code 



- push value in a onto stack 
pop value from stack into b 



13.3.2 Special names 

The following special names are available as constants inside asm expressions. 

.wssiZE Evaluates to the size of the current procedure's workspace. This will 
be the workspace offset of the retum address, except within a repli- 
cated PAR, where it will be the size of that replication's workspace 
requirement. 

. VSPTR Evaluates to the workspace offset of the vector space pointer. When 
it is used inside a replicated PAR, it points to the vector space pointer 
for that branch only. A compile time en^or is generated if there is no 
vector space pointer because no vectors have been created. 

, STATIC Evaluates to the workspace offset of the static link. When if is used 
inside a replicated par it points to the static link for that branch only. 
A compile time en-or is generated if there is no static link. 

For example, to determine the retum address of a procedure, the following could 
beusediLDL .wssize. 

It is not checked that these names are used sensibly, for example, J , wssize is 
legal even though it has no useful effect. 

13.3.3 Labels and jumps 

Labels may be defined inside an ASM construct. Labels are in scope for the entire 
procedure or function; thus both forward and backward references are permitted. 
It is illegal to declare two labels with the same name in the same routine. 

To insert a label into the sequence of instructions, put the name of the label, 
preceded by a colon, on a line of its own. When the label is used in an instmction, 
the name is again preceded by a colon. For example: 

ASM 

some instructions 
:FRED 

some more instructions 
CJ :FRED 

Currently labels are declared in a different namespace from ordinary identifiers; 
thus it is possible to have both a label x and a variable x in scope at the same time; 
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the label is recognized in context (following a ': ')- This will not necessarily be true 
in all implementations. 

Branches may only be made to a label defined within the same procedure or func- 
tion. It is pemiitted to branch to a PROC or FUNCTION which is in scope; it is up to 
the assembly programmer to load the parameters for the call correctly. 

13.3.4 Workspace zero 

Some transputer instructions make use of data at the current workspace pointer, 
known as 'workspace zero'. These instructions are OUTBYTE, OUTWORD POST- 
NOPMSN and the ALT disabling instructions. 

If these instructions are used Inside ASM, it is the programmer's responsibifity to 
reserve this location by means of the allocation: 

PLACE name AT WORKSPACE n : 

See section 13.1.2. 



13.3.5 Below workspace sEots 

Some instructions require various words at small negative offsets of workspace to 
be reserved. The compiler automatically reserves these when it sees the following 
instructions inside an ASM statement. 



Instructions 


Negative offsets 


IN OUT OUTBYTE OUTWORD 


3 


ALT ALTHT ENBC ENBS 


3 


DISC DISS 


3 


VINVOUTLDCKT 


3 


ENBGDISGGRANT 


3 


TIN TALT TALTWT ENBT DIST 


5 



13.3.6 Channels 

Channels may be accessed in ASM; they are considered to be a pointer to a channel 
word. Thus 'loading' a channel will load a pointer to the channel word, and loading 
the 'address' of a channel will load a pointer to a pointer to the channel word. 



13.3.7 Programming notes 

1 Floating-point (fp) registers cannot be loaded directly; they must be loaded 
or stored by first loading a pointer to the register into an integer register and 
then using the appropriate floating-point instruction. 
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2 The operands to the load pseudo-ops must be small enough to fit in a 
register and the operands to the store pseudo-ops must be word-sized 
modifiable elements. 

3 Code insertion using the 6UY constmct 1$ obsolescent. 

13.4 Dynamic code loading 

The toolset compiler pemiits the dynamic loading and execution of code using the 
procedures described in this section. 

These procedures are provided automatically by the compiler and are not refer- 
enced by a #DSE directive. The procedures allow you to write an occam program 
that reads in a compiled Occam procedure, and then calls it. The called procedure 
may be compiled and linked separately from the calling program and read in from 
a file. It is possible to pass parameters to the pnxedure, which must have at least 
3 formal parameters. 

Dynamically loadable code files can be created using the icollect 'K' option. By 
default they are given the . rsc extension. 

(Note that if you wish to dynamically load Occam functiohs, it is recommended 
that you call the FUNCTION indirectly from an Occam PRDC, and use non-VAL 
parameters to return the results to the calling environment). 

The procedures for setting up parameters before the call and for making the calE 
are outlined in the table below, and described in the following sections, with exam- 
ples. Further information and examples of this technique can be found in section 
5.3.5 of The Transputer Applications Notebook - Systems and Perfomiance. 



Procedure 


Parameter Specifiers 


KERNEL. RON 


VAL []BYTE code, 

VAL INT entry. offset, 

[ ] INT workspace , 

VAL INT no, of .parameters 


LOAD . INPUT . CHANNEL 


INT here, CHAN OF ANY in 


LOAD . INPUT . CHANNEL . VECTOR 


INT here, []CHAN OF ANY in 


LOAD . OUTPUT . CHANNEL 


INT here, CHAN OF ANY out 


LOAD . OUTPUT . CHANNEL . VECTOR 


INT here, []CHAN OF ANY out 


LOAD. BYTE. VECTOR 


INT here, VAL []BYTE bytes 



The collector tool icollect can produce code in a formal suitable for dynamic 
loading. The tool is described in Chapter 3 of the Occam 2 Toolset Reference 
Manual. 

13A1 Calling code 

The Occam 2 compiler recognizes calls of a procedure KERNEL. RUN with the 
following parameters: 
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PROC KERNEL. RUN 



(VAL []BYTE code, 
VAL INT entry. off set, 
[]INT workspace f 
VAL INT no. of .parameters) 



The effect of this procedure is to call the procedure loaded In the code buffer, 
starting execution at the iocation code [entry . offset] . 

The code to be called must begin at a word-aligned address. To ensure proper 
alignment either start the an-ay at zero or realign the code on a word boundary 
before passing it into the procedure. 

The workspace buffer is used to hold the local data of the called procedure. For 
details of the contentsof the workspace buffer see Figure 13.1 . The required size 
of this buffer and the code buffer must be derived from tnfonnation in the code file. 

The parameters passed to the called procedure should be placed at the top of the 
workspace buffer by the calling procedure before the call of kernel, run. The 
call to kernel -RON returns when the called procedure terminates. If the called 
procedure requires a separate vector space, then another buffer of the required 
size must be declared, and its address placed as the last parameter at the top of 
workspace. As calls of KERNEL .RUN are handled specially by the compiler it is 
necessary for no . of .parameters to be a constant known at compile time and 
to have a value ^ 3. 



workspace 

[(SIZE workspace) -1] 

vector space pointer 
or [ast parameter 



1st parameter 



workspace [0] 



saved Wptr 

[ no . of . paraiaeters+2 ] IHT 

parameters 
saved Iptr 



[ws * requirement] INT 

workspace of 
called procedure 



saved byKEBHEL.RUN 



loaded by caller 
(must be ^ 3) 



saved by kerhel . run 



Figure 13.1 Workspace buffer 
The workspace passed to kernel. rx;n must be at least: 

[ws . requirement + (no. of .parameters + 2)] INT 
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where ws . requirement is the size of workspace required, determined when the 
called procedure was compiled and stored In the code file, and no . of . parame- 
ters includes the vector space pointer ff it is required. The parameters must be 
loaded before the call of KERNEL . RUN. The parameter con-esponding to the first 
formal parameter of the procedure should be in the word adjacent to the saved 
Iptr word, and the vector space pointer or the last parameter should be adjacent 
to the top of workspace where the i^tr word will be saved. 



13,4.2 Loading parameters 

There are a number of library procedures to set up parameters before the call. 
These are: 

LOAD. INPUT. CHANNEL (INT here, CHAN OF ANY in) 

The variable here is assigned the address of the input channel in. 

LOAD. INPUT. CHANNEL -VECTOR (INT here, 

[]CHAN OF ANY in) 

The variable here is assigned the address of the base element of the 
channel array in (i.e. the base of the array of pointers). 

LOAD. OUTPUT. CHANNEL (INT here, CHAN OF ANY out) 

The variable here is assigned the address of the output channel out. 

LOAD. OUTPUT. CHANNEL. VECTOR (INT here, 

[]CHAN 07 ANY out) 

The variable here is assigned the address of the base element of the 
channel an^ay out (i.e. the base of the an^y of pointers). 

LOAD. BYTE. VECTOR (INT here, VAL []BYTE bytes) 

The variable here is assigned the address of the byte array bytes. 

Note that when passing vector parameters, ff the fomial parameter of the PROC 
called is unsized then the vector address must be followed by the number of 
elements in the vector, for example: 

LOAD, BYTE. VECTOR (param [ 0] , buffer) 
parain[l] := SIZE buffer 

Thus an unsized vector parameter requires 2 parameter slots. The size must be 
in the units of the array (not in bytes, unless it is a byte vector, as above). For multi- 
dimensional arrays, one parameter is needed for each unsized dimension, in the 
order that the dimensions are declared. 

All variables and an-ays should be retyped to byte vectors before using 
LOAD .BYTE .VECTOR to obtain their addresses, using a retype of the form; 
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[]BYTE b. vector RETYPES variable: 

LOAD .BYTE .VECTOR should alsQ be used to set up the address of the separate 
vector space. 

13.4.3 Examples 

This section gives two examples of dynamic loading. The first is a simple example 
showing how parameterless code can be input on a channel and loaded. The 
second is a more complex example showing how to set up and pass parameters 
into a dynamically loaded program. Sources can be found in the examples/ 
manuals/dynamic directory. 

Example 1 : load from link and run 

This is a simple procedure to load a (parameterless) code packet from a link and 
run it. The type of the packet is given by the protocol: 

PROTOCOL CODE. MESSAGE IS INT: ;[] BYTE; INT; INT 

The code is sent first, as a counted an"ay, followed by the entry offset and work- 
space size. 

PROC run. code (CHAN OF CODE. MESSAGE input, 

[]INT nin* vector, [)BYTE code. buffer) 
VAL no . parameters IS 3 : — smallest allowed 
INT code. lengthjentry. off set, work. space. size: 
INT total.work. space. size: 
SEQ 

input ? code* length: -.code. buffer; 

entry. offset; work, space. size 
total . work . space . size : = 

work. space. size + (no. parameters + 2) 
[]INT work, space IS [run. vector FROM FOR 

total . work . space .size] 
KERNEL. RUN (code, buffer, entry. offset, 
work. space, no. parameters) 



Example 2: system loader 

This example shows how to set up parameters prior to mnning code loaded from 
a file. It is assumed that the code requires use of a separate vector space. 

Consider a process with an entry of the form: 

PROC process (CHAN OF SP fs, ts, []INT buffer, 
VAL BOOL debugging, INT result) 
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The two channel parameters f » and ts handle output from and Input to the file 
server; the INT vector acts as a buffer. The two channels and the buffer are the 
same parameters as are provided by the bootstrap code added by the collector tool 
(see Chapter 3 in the Occam 2 Toolset Reference Manuaf), and the example takes 
advantage of this. The fourth parameter is a value parameter that will not be 
changed by the process, so only the value needs to be passed. The final parameter 
is an INT that will be changed by the process, and its address must be passed into 
the procedure. 

The calling program is shown below. The program reserves 256 bytes for the code 
that is to be read in; if you use this program make sure you modify this value to suit 
the size of your own code. 

fINCLUDK "hostlo.inc" 

PROC call. program (CHAH OF SP fa, ta, [JIHT free. memory) 

"~^ Variables for holding code and entry and workspace 

■-^ data read from file 

[256]BYTS code: 

IHT code . length , entry. off set; work. space. size: 

INT vector . space . size : 

INT result: — Variable used by process 

VAL debugging IS TRUE: — Value param for process 

VAL no.params IS 7: — No. of parameter slot;s 

— Heed 1 slot per parameter + 1 for the size of the 

— array parameter -i- 1 for the vector space pointer 

SSQ 

— Read in code and data a]>out code 

— Slice up memory vector for use by process 

— Reserve work space requirement for process 
[]INT ws IS [free. memory FROM FOR 

work . space . size -f (no.params + 2]]: 
-» Reserve vector space requirement for process 
[]INT vs IS [free. memory FROM SIZE ws FOR 
vector . space . si ze ] : 

— Reserve remainder of memory for use 
" — as process parameter buffer 

[]IHT buffer IS 

[free. memory FROH (SIZE ws) + (SIZE vs) FOR 
(SIZE free .memory) - ((SIZE ws) + {SIZE vs] ) ] : 
SEO 

— Reserve slot in ws for parameters 

[]INT parameter IS 

[ws FROH work. space. size 4- 1 FOR no.params]: 

SEQ 

LOAD. INPUT. CHANNEL (parameter [0] , fs] 
LOAD.OnTFaT.CHANNEL(parameterIlj , ts) 
— Retype buffer to take its address 
[]BYTE b. buffer RETYPES buffer: 
LQAD.BYTE.VECTOR (parameter [2] , b. buffer) 
parameterI3] := SIZE buffer 
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— Store VAL BOOL parameter 
parameter [4] := IHT debugging 

— Store address of TST parameter 
[]BYTE; b, result RETYPES result: 

LOAD. BYTS. VECTOR (parameter [5] , b. result) 

— Store pointer to vector spac^e 
[]6YTE b.vs RETTI^S vs: 

LOAD. BYTE. VECT0R(parameter[6], b.vs) 
— Run the process 

KERNEL. RUN ([code FROM FOR code . length] , 
entry. offset, va, no.params) 



This example first declares the variables and constants required for the process. 
The vector code should be of a size large enough to hold the code for the process. 
The values of the variables code , length, entry . offset, work . space .size 
and vector, space, size are determined from the data in the code file. 

Next the vector free . memory Is partitioned for use as the process's work space, 
vector space and as the variable vector used by the process. All vectors and vari- 
ables used by the process must be retyped as byte vectors so that their address 
can be determined by the predefined routine LOAD, BYTE .VECTOR. 

The parameters for the process are then set up. The unsized vector buffer is 
passed as an address followed the size of the vector, in integers. Note that the size 
of buffer, not b. buffer, is used. 

The partitioning of the free memory buffer is illustrated in Figure 13.2. 







-•" Top of free memory 

va + vs 
ws 

— start of free memory 




buffer 


vectorspace 


Wptr 


vector space address 


parameters 


Iptr 


workspace 







Figure 13.2 Partitioning of free memory 
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13.5 Extraordinary use of links 

13.5.1 Introduction 

The transputer link ardiitecture provides ease of use and compatibilfty across the 
range of transputer products. It provides synchronized communication at the 
message level which matches the OCcam model of communication. 

In certain circumstances, such as communication between a development system 
and a target system, it is desirable to use a transputer link even though the synchro- 
nized message passing of Occam is not exactly what is required. Such extraordi- 
nary use of transputer Jinks is possible but requires careful programming and the 
use of some special occam procedures. 

The use of these procedures is described in this chapter. To use them in a compila- 
tion unit, the directive #DSE "xlink . lib" should be inserted at the top of the 
source for that unit. For details of the procedures see section 1 .10 in the occam 
2 Toolset Language and Ubranes Reference Manual. 

13.5.2 CJarificatlon of requirements 

As an example, consider a development system connected via a link to a target 
system. The development system compiles and loads programs onto the target 
and also provides the program executing in the target with access to facilities such 
as a file store. Suppose the target halts (because of a bug) whilst It is engaged in 
communication with the development system. The development system then has 
to analyze the target system. 

A problem will arise if the development system is written in 'pure' occam. !t is 
possible that when the target system halts, the development system is in the 
middle of communicating on a link. As a result, the input or output process will not 
terminate and the development system will be unable to continue. This problem 
can occur even where an input occurs in an alternative construct together with a 
timeout (as Illustrated below). When the first byte of a message is received the 
process performing the altemative is committed to input; the timer guard cannot 
subsequently be selected. Hence, if insufficient data is transmitted the input will not 
temiinate. 

ALT 

TIME ? AFTER timeout 

from. other. system ? message 

It is important to note that the problem arises from the need to /lecov^erfrom the 
communication failure. It is perfectly straightfonvard to detect the failure within 
'pure' Occam and this is quite sufficient for implementing resilient systems with 
multiple redundancy. 
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13.5.3 Programming concerns 

The first concern of a designer is to understand how to recognize the occurrence 
of a failure. This will depend on the system; for example, in some cases a timeout 
may be appropriate, In others the failure may need to be signalled to another 
process on a channel. 

The second concem is to ensure that even if a communication fails, all input 
processes and output processes will terminate. As this cannot be achieved directly 
in Occam, there are a number of library procedures which perfomi the required 
function. These are described beiow. 

The final concem is to be able to recover from the failure and to re-estabfish 
communication on the link. This involves reinitializing the link hardware; again 
there is a suitable library procedure to allow this to be performed, 

13.5.4 Input and output procedures 

There are four library procedures which implement input and output processes 
which can be made to terminate even when there is a communication failure. They 
will temiinate either as the result of the communication completing, or as the result 
of the failure of the communication being recognized. Two procedures provide 
input and output where communication failure can be detected by a simple timeout, 
the other two procedures provide input and output where the failure of the commu- 
nication is signalled to the procedure via a channel. The procedures have a 
boolean variable as a parameter which is set true if the procedure terminated as 
a result of communication failure being detected, and is set FALSE otherwise. If the 
procedure does terminate as a result of communication failure then the link 
channel can be reset. 

All four library procedures take as parameters a link channel c (on which the 
communication is to take place), a byte vector mess (which is the object of the 
communication) and the boolean variable aborted. The choice of a byte vector 
as the parameter to these procedures allows an object of any type to be passed 
along the channel provided it is retyped first. Channel retyping (see section 13.2) 
may be used to pass channels of any protocol to these procedures, 

The two procedures for communication where failure is detected by a timeout take 
a timer parameterTiME, and an absolute timet. The procedures treat the commu- 
nication as having failed when the tme as measured by the timer time is after 
the specified time t. The names and the parameters of the procedures are as 
follows: 

InputOrFaii.t(CHAN OF ANY c, [JBYTE mess, 
TIMER TIME, 
VAL INT t, BOOL aborted) 

OutputOrFail.t(CHAN OF ANY c, VAL []BYTE mess, 
TIMER TIME, 
VAL INT t, BOOL aborted) 
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The other two procedures provide communication where failure cannot be 
detected by a simple timeout. In this case failure must be signalled to the Inputting 
or outputting procedure via a message on the channel kill. The message is of 
type INT. The names and parameters to the procedures are as follows: 

InputOrFaiI,c{CHAN OF ANY c^ []BYT£ mess, 

CHAN OF INT kill, BOOL aborted) 

OutputOrFail.c{CHAN OF ANY c, VAL []BYTE mess, 
CHAN OF INT kill, BOOL aborted) 

13.5.5 Recovery from failure 

To reuse a link after a communication failure has occurred it is necessary to rein- 
itialize the linlc hardware. This involves reinitializing both ends of both channels 
imptemented by the link, Furthemore, the reinitialization must be done after all 
processes have stopped trying to communicate on the link. So, although the 
inputOrFail andOutputOrFail procedures reset the link automatically when 
they abort a transfer, it is necessary to use the ffth library procedure Rein- 
itialise (CHAN OF ANY c) after it is known that all activity on the link has 
ceased. 

The Reinitialise procedure must only be used to reinitialize a link channel 
after communication has finished. If the procedure is applied to a link channel 
which is being used for communication the transputer's error flag will be set and 
subsequent behavior is undefined. 

13.5.6 Example: a development system 

For our example consider the development system illustrated in Figure 13.3. 















Development 
System 


Target 
System 




Link 











Figure 13.3 Development system 

The first step in the solution is to recognize that the development system knows 
when a failure might occur, and hence knows when it might be necessary to abort 
a communication. 

When the development system decides to reset the target it can send a message 
to the interface process directing it to abort any transfers in progress. It can then 
reset the target system (which resets the target end of the link) and reinitialize the 
link. 
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The example program below could be that part of the development system which 
runs when the target system starts executing and continues until the target is reset 
and the link is reinitialized. 

SEQ 

CHAN OF AKY term nate. input, terminate . output : 

interface process 

monitor process 
reset target system 
Reinitialise (link. in) 
Reinitialise {link . out) 

The monitor process will output on terminate . input and terminate . output 
when it delects an eror in the target system. 

The interface process consists of two processes running in parallel; one process 
outputs to the link, and the other inputs from the link. As the structures of the two 
processes are similar only the output process is illustrated here. 

If there were no need to consider the possibility of communication failure the 
process might be: 

WHILE active 
SEQ 

ALT 

terminate . output ? any 

active := FALSE 
from.dev. system ? message 

link . out ! message 

This process will loop, forwarding input from from. dev- system to link. out» 
until it receives a message on terminate . output. However, if the target system 
halts without inputting after this process has attempted to forward a message, the 
Interface process will fail to terminate. 

The following program overcomes this problem: 

WHILE active 
BOOL aborted ; 

SEQ 

ALT 

terminate . output ? any 

active := FALSE 
from. dev. system ? word 
SEQ 

OutputOr Fai 1 . c ( link . ou t , mes sage ^ 

terminate . output , aborted) 
active := NOT aborted 



72TDS366 01 March 1993 



260 13.6 Scheduling 



This program is always prepared to input from terminate . output, and is 
always terminated by an Input from terminate . output. There are two possible 
cases. The first Is where a message is received by the Input which then sets 
active to FALSE. The second is where the output is aborted. In this case the 
whole process is terminated because the variable aborted would then be true. 



13.6 Scheduling 

Processes In occam may have one of two priorities, high or low A high priority 
process will be executed in preference to a low priority process if both are active, 
so that a low priority process will be interrupted. The PRI PAR construct is used 
to assign priority to processes. 

Scheduling in Occam is achieved using the transputer's scheduler which main- 
tains a list of processes. The following predefined procedure may be used to affect 
scheduling: 

• RESCHEDULE { ) -insertsinstructlonslntotheprogramtocausethecurrent 
process to be moved to the end of the current priority scheduling queue, 
even if the current process is a 'high priority' process. 

This procedure is recognized automatically by the connpilerand does not need to 
be referenced by the #USE directive. 



1 3.7 Setting the error flag 

The transputer error flag can be explicitly set from software using the following 
predefined procedure: 

• CAUSEERRORO - inserts a seterr instruction into the program. If the 
program is In STOP or UNIVERSAL mode it inseri:s a stopp instruction as 
well. 

This procedure is recognized automatically by the compiler and does not need to 
be referenced by the #USE directive. 

CAUSEERROR sets the transputer en'or flag no matter what the error mode of the 
compilation. This is distinct from the Occam primitive process STOP, which only 
sets the flag if the compilation is in HALT mode. 
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A Configuration 
language definition 



This appendix defines the syntax of the occam configuration language. This 
should be considered as extending the syntax of Occam, 

A.1 Notation 

Syntax definitions are presented in a modified Backus-Naur Form (BNF). Briefly, 
the form is as folJows: 

• Each phrase definition consists of an equality expression built up using an 
equals sign to separate the two sides. 

• Terminal strings of the language — those not built up by rules of the 
language — are printed in teletype font e.g. NODE. 

• Alternatives are separated by vertical bars (T). 

• Optional sequences are enclosed in italic square brackets ['[ and '/), 

• Items which may be repeated zero or more times appear in braces (T and 

n 

• (o, X} represents a list of zero or more items of type 'x' separated by 
commas. 

• {i, x} represents a list of one or more items of type 'x' separated by 
commas. 



A.2 Introduction 

A configuration program file contains a sequence of specifications. These specifi- 
cations should include one hardware description (containing at least one node 
declaration), and one software description. Optionally there may be edge declara- 
tions and arc declarations. An optional mapping may appear either before of after 
the software configuration, but after the declaration of any nodes, edges or arcs 
which it references. Normal occam scope rules apply. 

The #IKCLUDE mechanism may be used to incorporate hardware descriptions, 
software descriptions, or any other source text from other files. 

The #USE statement may be used to reference pre-complled code, either at the 
outer level, or within the software description. 
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A,3 New types and specifications 

This section defines the new Occam types introduced by the configuration 
language. 

Tlie syntax adds [he new primitive types NODE, EDGE and arc, and structures 
CONFIG, NETWORK and MAPPING to the occann language. 

NODE declarations introduce processors {nodes of a graph). These processors are 
physical if their type and memory size attributes are defined as part of the hardware 
description, and logical otherwise. 

EDGE declarations introduce external connections of the hardware description. 

ARC declarations introduce named connections {arcs of a graph). Each arc 
connects two edges, which may be attributes of nodes, or declared edges. 
Connections need only be named if it is required to force a particular mapping of 
channels, or if names are required to aid debugging. 

NETWORK declarations Introduce the hardware description. 

CONFIG declarations introduce the software description. 

MAPPING declarations introduce the mapping description. 



A.3.1 Syntax of configuration description 


configuration 


= hardware, deschptbn 
software, description 
[mapping] 
1 specification 
configuration 


speciffcation 


VAL 


ptimiUve type 


^ NODE 
= EDGE 




= ARC 



A.4 Hardware description 

The NETWORK keyword introduces a handware description, an optionally named 
structure which describes the types, connectivity and attributes of previously 
declared processor nodes. Connections are defined in CONNECT statements. 
Attributes are given values in SET statements. The attributes of a processor node 
include an an-ay of edges which are its links, a string which defines its processor 
type, and an integer which is the memory size in bytes. 

Connections and attribute settings may be combined in any order using the DO 
constructor, including replication and conditionals. For each node which has a type 
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defined to be a processor the attributes with predefined names type and 
memsize must be set once only. The connections connect declared edges and 
edges of nodes, which have the predefined attribute name link. The boolean 
attribute root may be set to true for only one node in a networi^without a connec- 
tion to the predefined edge HOST. The attribute romsize defines the size in bytes 
of read only memory on a node. Attributes are referenced by subscripting node 
names with attribute names in brackets. 



A.4.1 Processor attributes 

This section describes processor attributes defined in the OCCam configuration 
language. 

The following processor attributes can be defined in the network description: 

• link - used by processor and networi< nodes to define interconnection. 
Only defined if the type attribute has already been defined. 

• memsize - used by processor nodes to define memory size. 

• root - defines the root processor if there is no host connection. 

• romsize - specifies the size of ROM attached to the processor, 
expressed as an integer 

• type - used by processor nodes to define processor type. 

The following processor attributes can be defined in the mspping description: 

• linkquota - suggests the maximum number of links on the associated 
processor that should be used by the virtual channel routing system. 

• location. code, location. ws, location, vs, - used by process 
nodes to specify the absolute locations of their code, wort^pace, and 
vectorspace segments. 

• order. code, order .vs, order .vs - used to specify the ordering of 
code and data segments. 

• nodebug - disables debugging by the Inquest Toolset, Takes the vaiue 
TRUE or FALSE; the default is false. 

• noprof ile - disables debugging by the Inquest Toolset. Takes the value 
TRUE or false; the default is FALSE. 

• reserved - used by processor nodes to reserve memory. 

• routecost - defines within the range 1 to 1000000 the associated cost 
of through-routing data through this processor for other processor's virtual 
channel traffic. 
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tolerance - controls with any value between and 1000000 how much 
the particular processor concerned can be used for the provision of load- 
sharing through-routing paths for other processors. 



A.4.2 Syntax definition 

hardware. description 



spec'ficatior) 



node. declaration 
edge. declaration 
arc .declaration 

networkMm 



connection.item 

edge 

aitrihuie. setting 

device 

attribute.assignmeni 

attribute 

attribute.value 

condiiional.network.ftem 

networl< choice 

guarded .network, choice - 



NETWORK [ networkname ] 
network.item 

I specification 
hardware, description 

node.declaration 
I edge.dedaration 
I arc.declarafion 
I VAL 

{o [ expression ] }NODE nodename : 
{o [ expression ] } edge edgename : 
{o [ expression ] } ARC arcname : 

DO 

I DO replicator 
network.item 
connection.item 
aitnbute. setting 
conditional, network, item 
SKIP 
STOP 

abbreviation 
netwotic.item 

CONNECT edge to edge f with arcname ] 



I 



edgename 
device "[linkl' 



"["expression"]' 



SET device { attribute.assignment } 

nodename { q [ subscript ] } 

{ 1 , attribute } : = { i , attribute.value } 

ahribute.name { o / [ subscript ] } 

expression 

IF 

{network choice] 

guarded, network.choice 
conditional, network, item 

boolean 
network.item 
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A.5 Software description 

A COKFIG declaration introduces the software description as an Occam process. 
Additional specifications and processes are added to occam: the processor name 
in a PROCESSOR statement may be a physical processor name or the name of a 
iogical processor which is mapped onto a physicai processor. A channel allocation 
may ailocate up to two channels onto a named arc of the network. 



A.5.1 Syntax definition 

software, descnpfion 



CONFIG [config.name] 
placedpar 

I speciftcation 

software. description 



placedpar 



conditional.network.ltem 



network choice 



guarded .network.ctioice 



/PLACEDjPAR 

{placedpar} 
[ PLACED } PAR replicator 

placedpar 
PROCESSOR processorname 

processMame 
specification 
placedpar 

conditionaLnetwork.item 
SKIP 
STOP 

IF 

{network choice) 

guarded.network.choice 
conditional.network. item 

boolean 
network.item 



A.6 Mapping structure 

The keyword MAPPING introduces an (optionally named) mapping structure which 
may be either before or after the software description. DO and if constructs may 
be used as in Occam, skip and stop are aEso allowed. 

Mappings are introduced by the map keyword. A mapping may be used to 
associate logical processors with physical processors (code mapping), and chan- 
nels with arcs (channel mappings). 
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A.6 Mapping structure 



In code mappings a logical processor may appear on the left hand side of only one 
mapping item whereas a physical processor may appear on the right hand side of 
more than one mapping item. A code mapping may include a priority clause, 
introduced by PRI, which will determine the priority at which the process will mn. 
SET may be used to define processor attributes (see section A,4,1). 

In channel mappings the arc must connect the nodes onto which the processes 
using the channels are mapped. The effect of channel mappings is identical to the 
corresponding channel allocations which may appear in the software description. 
Mappings involving single channels may use the PLACE statement. 

Channel mappings are optional except In the case where one end of the arc is an 
external edge. (The configurer will normally choose a mapping from its knowledge 
of the connectivity of the hardware and the implied connectivity derived from the 
use of channels as in the software description.) 



A.6.1 Syntax definition 

mapping 



MAPPING [ mapping.name ] 
mappinglem 



mapping.item 



I specification 
mapping 

code, mapping 
I channel.mapping 
I channeLaftocation 

I DO 

mapping.item 
I DO replicator 

mapping.item 
I conditional.map.item 
I SKIP 
I STOP 
I abbreviation 
mapping.item 
I attribute.setting 



code. mapping 

priority.clause 

processor.list 

processid 

processorname 

node 



MAP processor.list onto node [priority.cfause] 

PRI expression 

{ 1 , processid ] 

processorname (o [ subscript ] ] 

node.name 

node.name {o I subscript ] } 



channel.mapping 
cliannel.list 



MAP channeUist omo arc 
{ 1 , channelid } 
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channelid ~ channel. name { o [ subscript ] } 

Bra - arc.name {q [ subscript ] ] 

channel.allocation - place { channeUist } on arc : 

attribute. setting = set device { attribute.assignment } 

device - nodename { q [ subscript ] } 

attribute.assignment - {j , attribute} := {i , attribute.value } 

attribute = attribute,name [q , [ subscript ] } 

attribute.value = expression 



conditionaimap.item = if 

{mapping.clioice} 
mapplng.choice = guarded. mapping. choice 

I conditionaLmap.item 



guBrded.mapping.choice - boolean 

map.ltem 



AJ Constraints 

The following constraints apply to al! configurations: 

• All physical processors whose types are set must be connected to each 
other. 

• Any physical processor whose type is set must have fts memsize set. 

• Logical processors may only be mapped onto physical processors whose 
type has been set 

• Channels connecting processors of different word size must not use proto- 
cols based on the type int. 

• A priority expression must evaluate to (high) or 1 (low). 

• INT array constructors such as [1,2,3] are not accepted for 16-bit 
processors. They should be converted into INT16 arrays. 

• It is not permitted to RETYPE int constants into other types for 16-bit 
processors. IKT16 constants should be used instead. 

• INT expressions are treated as INT32S. Thus MOSPOS INT evaluates to 
the same value as MOSTPOS INT32. Where this is a problem, i.e. it causes 
a 1 6-bit integer overflow, the configurer will generate an eror 
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B Equivalent data 
types 

This appendix lists equivalent data types to use when passing parameters to 
external routines and receiving function return values. The information is pres- 
ented with both Occam and C as the calling language. 

B.I Occam as the calling language 

B.1 .1 Parameter passing 

The following table lists the equivalent data types to use when passing parameters 
from Occam to C. The first column gives the C formal parameter, the second and 
third columns give the Occam actual parameter type to pass. Where there is no 
true equivalent the action to take is given. 



C formal parameter 


Occam actual parameter 


(32 bit) 


(16 bit) 


char 

unsigned char 


VAL BYTE 


VAL BYTE 


signed char 


No direct equivalentf 


No direct equivalentf 


short 
signed short 


No direct equivalentf 
{see Note 1 ) 


VAL INT 
VAL INT16 


unsigned short 


No direct equivalentf 


No direct equivalentf 


int 

signed int 
enimi 


VAL im 

VAL INT32 


VAL INT 
VAL INT16 


unsigned int 


No direct equivalentf 


No direct equivalentf 


long 
signed long 


VAL INT 
VAL INT32 


No direct equivalentf 


unsigned long 


No direct equivalentf 


No direct equivalentf 


float 


VAL REAL32 


No direct equivalentf 


double 


No direct equivalentf 


No direct equivalentf 


struct 
union 


No direct equivalentf 


No direct equivalentf 


char * 
unsigned char * 


BYTE 


BYTE 


signed char * 


No direct equivalentf 


No direct equivalentf 
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B.I Occam as the calling language 



short * 
signed short * 


INT16 


INT16 
INT 


unsigned short * 


No direct equivafentf 


No direct equivalentf 


int * 

signed int * 
enum * 


INT 
INT32 


INT 
INT16 


unsigned int * 


No direct equivalentf 


No direct equivalentf 


long * 
signed long * 


INT 
INT32 


INT32 


unsigned long * 


No direct equivalentf 


No direct equivalentf 


float * 


KEAL32 


REAL32 


double * 


re:al64 


REAL64 


struct * 
union * 


No direct equivalentf 


No direct equivalentf 


channel * 


CHAN 


CHAN 


array 


See section 11.1.4. 


See section 11.1.4. 


tThere is no direct type equivalent in Occam. Either recode the C program or 
pass the parameter in another fonn. 

Note 1: A C short on a 32 bit processor is stored in 32 bits with the upper 16 
bits zeroed. In occam an inti6 on a 32 bit processor is also stored as a 32 
bit value, however, in this case the upper 16 bits are ignored and not zeroed. 
Hence C short and occam int16 are not directly equivalent. 



B.1.2 Return values 

The following table gives the occam data type to use when receiving retum values 
from C functions. Equivalents are given separately for 32 bit and 1 6 bit transputers. 



C function type 


Occam function type 


(32 bit) 


(16 bit) 


char 
unsigned char 


BYTE 


BYTE 


signed char 


No direct equivalentf 


No direct equivalentf 


short 
signed short 


INT16 


INT 
INT16 


unsigned short 


No direct equivalentf 


No direct equivalentf 


int 

signed int 
enum 


INT 

INT32 


INT 
INT16 


unsigned int 


No direct equivalentf 


No direct equivalentf 


long 
signed long 


INT 
INT32 


INT32 
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unsigned long 


No direct equivalentt 


No direct equivalentt 


float 


FEAL32 


REAL32 


double 


re:ai.64 


REAL64 


struct 
union 


No direct equivalentt 


No direct equivalentt 


Any pointer type 


No direct equivalentt 


No direct equivalentt 


fThere is no direct type equivalent in Occam. Either recede the C program or 
pass the parameter in another form. 



B.1.3 Example of passing parameters from Occam to C 

The following examples show two C functions with a variety of formal parameters 
along with the occam code which can calf them. The code for 32 bit and 16 bit 
transputers is given separately. 

C functions to be called on a 32-bit transputer: 



int cfuncl (int parml} ; 
tpragma lMS_nolin]c(cfuncl) 



I* remove the gsb hidden 
parameter */ 



void cprocl(char c, int i, 

long 1, float f, 

char *cp, short *sp^ 

int *ipf long *lpj. 

float *fp/ doiible *t^, 

int arrayl [3] ^ 

int array2[] , const int array21en) ; 



fpragma IMS_nolin]t (cprocl) 



i* remove the gsb hidden 
parameter */ 



int cfiincl (int parml) 
{ 

} 



return parml 



10; 



void cprocl (char o., int i, 

long 1, float f, 

char *cp, short *sp, 

int *ip/ long *lp, 

float *fp, double *dp, 

int arrayl [3] , 

int array2[J, const int array21en) 



( 



int j ; 



*cp = c; 

*sp = (short) c; 

*ip = i; 

*lp = 1; 
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*fp = f ; 

*dp = (double) i; 

for Ej = 0; j < 8; j-H-) 

arrayl [ j ] = 42 ; 
for {j =0; j < array21en; j++) 

array2[j] = array21en; 
) 



Occam code to call the above C functions on a 32 bit transputer 

tPRAGMi EXTERNAL "IHT FDMCTIOKf cfuncltVAL INT parml) = 100" 
#PRAGMA EXTEE^NAL "PROC cprocl (VAL BYTE c, VAL INT i, * 

* VAL INT32 1, ^na. REaX32 f , * 

* BYTE ep, TWri.6 8p, * 

* INT ip, INT32 Ip, * 

-* REAL32 fp, REALS! dp, * 

* [8)INT arrayl, []INT array2) ^ 100" 

BYTE c^ cp; 

INT i, ip, result: 

INT16 sp: 

INT32 1; Ip: 

REAL32 f, fp: 

REAL64 dp: 

[8] INT arrayl: 

[5] INT Mray2: 

SEQ 

result := cfuncl (1) 

cprocl (Cr i, 1, tf cpf sp, ip, Ip, fp, c^, arrayl, array2) 

C functions to be called on a 16 bit transputer: 

int cfuncl (int parml) ; 

#pragina IMS_nolinJt (cfuncl) /* remove the gsb hidden 

parametar */ 

void cprocl (char c, int i, 

short A, char *cp, 

short *sp, int *ip, 

long *lp, float *fp, 

double *<3^, int arraylfS], 

int array2ny const int array21en) ; 

fpragma IMS_nolin]c (cprocl) /* rranove the gsb hidden 

parameter */ 

int cfuncl (int parml) 
{ 

return parml * 10; 
) 

void cprocl (char c^ int i, 

short s, char *cp, 
short *sp, int *ip, 
long *lp, float *fp. 



72 IDS 366 01 March 1993 



B Equivalent data types 275 



double *dp, iut arrayl[8], 

int array2 [ ] ^ const int array21en) 



int j; 



} 



*cp 


= c; 






*sp 


= a; 






*ip 


= i; 






*lp 


= (long)i; 






*fp 


= (float) i; 




*dp 


= (double) 


1 i; 




for 


(J = 0; j 


< 


3; j++) 


axrayl[j] = 


42 


1 ; 


for 


Ij = 0; j 


< 


array21en ; 


array2[j] = 


array 21en; 



j++) 



Occam code to call the above C functions on a 16 bit transputer 

IPRAGMA EXTERHAL "THT rOKCTlON cf unci [ VAX INT patml) = 100" 

#PRAGMft EXTERNAL "PROC cprocl (VAL BYTE C, VM* I»T i, * 

* Y&L INT16 s, BYTE cp^ * 

* INT1£ sp, INT ip, * 

* 1NT32 Ip^ REAL32 fp, * 

* BEai64 dp, * 

+ [S]INT arrayl, HINT array2) = 100" 

BYTE c, cp: 

INT i, ip, result: 

INT16 3, sp: 

INT32 Ip: 

REAL32 fp: 

REAL64 dp: 

[8] INT atrayl: 

[5] INT array2: 

SEQ 

result := cfuncl{i) 

cprocl (c, i, s, cp, sp, ip, Ip, fp, dp, arrayl, array2) 



B.2 C as the calling language 



B.2.1 Parameter passing 

The following table lists the equivalent data types to use when passing parameters 
from C to Occam. The first column gives the occam fomial parameter, the second 
and third columns give the C actual parametertype to pass. Where there is no true 
equivalent the action to take is given. 
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Occam formal parameter 


C actual parameter 


(32 bit) 


(16 bit) 


VAL BOOL 


int 

(value must be or 1) 


int 

(value must be Oor1) 


VAL BYTE 


char 
unsigned char 


char 
iinsigned char 


VAL INT16 


short int 


short int 
int 


VAL INT32 


int 
long int 


long int * 


VAL INT64 


No direct equivalentt 


No direct equivalentt 


VAL INT 


int 


int 


VAL REAL32 


float 


float * 


VAL REAL64 


double * 


double * 


VAL array 


See section 11.1.4. 


See section 11.1 A 


BOOL 


char * 

unsigned char * 
(value pointed to must 
beOorl) 


char * 

unsigned char* 
(value pointed to must 
beOorl) 


BYTE 


char * 
unsigned char * 


char * 
unsigned char * 


INT 16 


short int * 


short int * 
int * 


INT32 


int * 
long int * 


long int * 


INT64 


No direct equivalentt 


No direct equivalentt 


INT 


int * 


int * 


REAL32 


float * 


float * 


REAL64 


double * 


double * 


CHAN 


Channel * 
(see Note 1) 


Channel * 

(see Note 1) 


PORT 


No direct equivalent! 


No direct equivalentt 


TIMER 


Pass nothing (see 
page 203). 


Pass nothing (see 
page 203). 


array 


See section 11.1.4. 


See section 11.1.4. 


tThere is no dtrect type equivalent in C. Either recode the Occam program or 
pass the parameter in another form. 

Note 1; Channel Is an INMOS specific type declared in the C header file 
channel. h. 
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B.2.2 Return values 

The following table outlines the conventions that must be followed when receiving 
Occam ftjnction return values In C. 



Occam function type 


C function type 


(32 bit) 


(16 bit) 


BOOL 


int 


int 


BYTE 


char 
unsigned char 


char 
iinsigned char 


INT16 


short int 


short int 
int 


INT32 


int 

long int 


long int 


INT 64 


No direct equivalentt 


No direct equivalentt 


INT 


int 


int 


REAL32 


float 


float 


REAL64 


doxable 


double 


fThere is no direct type equivalent in C. Either mcnde the occam program or 
pass the parameter in another form. 



B.2,3 Example of passing parameters 

The following exampfe shows an Occam function and an occam procedure with 
a variety of formal parameters, along with the C code which can call them. The 
calling code for 32 bit and 16 bit transputers is given separately. The occam 
routines to be called are as follows: 

XNT32 FUNCTION ocfuncl (VM. IWT32 paxml) IS parml : 

PROC ocprocl(VM, BYTE vb, 

VAl INT16 viie, 
VAL INT32 vi32, 
VAL INT vi, 
VAL REAL32 vr32, 
VAL REAL64 vrG4, 
VAL BOOL vbo, 
VAL []INT varrl, 
VAL [8] INT varr2, 
BYTE b, 
IKT16 il6, 
INT32 i32, 
INT i, 
REAL32 r32, 
REAL64 r64, 
BOOL bo, 
[]INT arrl, 
13] INT arr2) 
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SEQ 

b := -vb 
il6 := vil6 
132 :^ vi32 
i :^ vi 
r32 := vr32 
r64 := vt64 
bo := vbo 
arrl := varrl 
arr2 := var3c2 



The C code to call the above occam routines on a 16 bit transputer is as follows: 

#define ARRAX_SIZE_1 4 
#define ARRAy_SIZE_2 8 

extern long int ocf unci (long int parml) ; 

extern void ocproci [char vb, short int vilS, 
long int vi32, int vi, 
float vr32, double •Tr64, 
int vbo, 

int varrl IJ, const int varrl_size, 
int varr2[ARRay_SlZE_2] , 
char *b, short int *il6, 
long int *i32, int *i, 
float *r32, double *r64 , 
char *bo, 

int arrl[], const int arrl_^size, 
int arr2 [ARRArjSIZE_2] ) ; 

^pragma IMS_nolinlt (ocfuncl) 
Ipragma rwS_noIinJc (ocproci) 

long int li, result; 

char vb, b; 

short int vil6, il6; 

long int vi32, 132; 

int vi, i,* 

float vr32, r32; 

double vr64, r64; 

int vbo; 

char bo; 

int varrl [ARRAY_SIZE_1] , arrl [AimAY_SIZE_lI ; 

int varr2[ARRAY__SIZE_2] , arr2 [ARRA.Y_SIZE_2] ; 

result = ocfunel (li) ; 

ocproci (vb, vil6, vi32, vl^ vr32^ 4vr64, 
vbo, varrl, ARRAY_SI3E_1, varr2, 
£b, iLl€, £132, &L, &z32, izSA, 
fibo, arrl, ARRAY_SI2E_1, arr2) ; 
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This appendix provides a reference for the transputer instruction set as supported 
by assembly code insertion. For detailed specifications of the instructions, refer to 
the Transputer instruction set: a compiler writer's guide. 

Instructions listed in sections C.1 to C.7 can be used when 'full code insertion' is 
enabled by the 'w' command line option. Instructions listed in section C.8 can be 
used when 'sequential code insertion' is enabled by the 'G' command line option. 
Note: Only use those instructions which exist on the target processor may be used. 
For example, floating point instructions (see section C.5.1) may not be used onT4 
series transputers. 

C.1 Prefixing instructions 

The transputer instruction set is built up from 16 direct instructions, each with a 
4'bit argument field. The direct instructions include prefix instructions which 
augment the 4-bit field in a direct instruction which follows them by their own 4-bit 
argument field, effectively allowing the argument to be extended to 32 bits. 
Normally, the assembler will compute the prefix Instructions required for operand 
values greater than 4 bits automatically 

pfix prefix 

nfix negative prefix 



C.2 Direct instructions 

The direct instructions form the core of the transputer instruction set. Each direct 
instruction has a single operand, normally an integer constant, which will be 
encoded in the instruction itself and, if it is larger than will fit into the 4-bit argument 
field of the direct instruction^ into a series of pfix and nfix instructions as well. 

The transputer architecture is based around a three-register evaluation stack and 
a single base register Wreg. The load and store 'local' instnjctlons access a word 
in memory at a displacement from Wreg given by the operand value used. The 
displacement is scaled by the word size. The load and store 'non-local' instructions 
use the top evaluation stack register (Areg) as the base instead of Wreg, allowing 
computed base addresses to be used. 

The operand of they , cj and ca// instructions is interpreted as a byte displacement 
from the instmction pointer (program counter) register Iptr /dp/ is similar but takes 
its operand from Areg. 
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adc Add constant operand value to Areg. 

ajw Adjust worlcspace pointer Wreg by constant operand value (scaled 

byword length). 

call CalL 

cj Conditional jump i.e. 'jump if zero otherwise pop Areg'. As with 

jump , a label identifiermay be used as argument to this instruction. 

eqc Test if Areg equals constant; (result 'tme' or false', placed in Areg). 

j Jump: the argument may be an identifier indicating a label for the 

jump to go to; the assembler will compute the displacement 
required. 

fdc Load constant 

fdf Load local word 

Idlp Load pointer to local word 

Idnl Load non-local word 

Idnip Load pointer to non-local wonj 

opr 'operate': the argument to this instruction is a code indicating a 

zero-operand /nd/rec/ instruction to be executed. Most of the trans- 
puter instruction set Is made up of these indirect instructions. 
Normally you would use the mnemonic for the specific indirect 
instnjction which you require: the assembler will encode this as an 
opr instruction on your behalf. However, it is possible to use opr 
explicitly, for example to synthesize the instruction sequence for a 
new indirect instruction not supported by the T414 and T800 trans- 
puters. 

sti Store local word 

stnl Store non-local word 



C.3 Operations 

The instructions in this section are all indirect instructions built out of the opr 
instruction. None of these Instructions take an argument; instead, they work solely 
with the transputer evaluation stack. 

The arithmetic Instructions take their operands from the top of the evaluation stack 
(Areg, Breg) and push the result value back on the stack in Areg, 



add 


Add 


alt 


Alt start 


attend 


Alt end 


altwt 


Alt wait 


and 


Bit-wise and 


bent 


Byte count 
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bsub 


Byte subscript (Areg = Areg + Breg) 


ccnt1 


Check count from 1 


clftjalterr 


Clear halt-on-en-or 


csngi 


Check single 


csubO 


Check subscript ftxjm 


cwofd 


Check word 


diff 


Difference 


disc 


Disable channel 


diss 


Disable skip 


dist 


Disable timer 


div 


Divide 


enbc 


Enable channel 


enbs 


Enable skip 


enbt 


Enable timer 


endp 


End process 


fmul 


Fractional multiply (32-bit processors only) 


gajw 


General adjust workspace 


gcali 


General call (swap Areg+^lptr) 


gt 


Greater than (result 'true' or false', placed in Areg) 


in 


Input message 


iadd 


Long add 


lb 


Load byte 


Idiff 


Long difference 


tdiv 


Long divide 


Idpi 


Load pointer to instruction (Areg is byte displacement from Iptr) 


Idpri 


Load current priority 


Idtimer 


Load timer 


lend 


Loop end 


imul 


Long multiply 


IshI 


Long shift left 


Ishr 


Long shift right 


Isub 


Long subtract 


fsum 


Long sum 


mint 


Minimum Integer 


move 


Move block of memory (src: Creg dest: Breg len: Areg) 


mat 


Multiply 
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nonri 


Normalize 




not 


Bit-wise not 




or 


Bit-wise inclusive or 




out 


Output message 




outbyte 


Output byte 




outword 


Output word 




prod 


Product 




rem 


Remainder 




resetch 


Reset channel 




ret 


Return 




rev 


Reverse top two stack elements 




runp 


Run pnx^ss 




saveh 


Save high priority queue registers 




savel 


Save low priority queue registers 




sb 


Store byte 




seterr 


Set error 




sethafterr 


Set halt-on-eiTOr 




shI 


Shift left 




shr 


Shift right 




starip 


Start process 




sthb 


Store high priority back pointer 




sthf 


Store high priority front pointer 




stfb 


Store low priority back pointer 




stif 


Store high priority back pointer 




stoperr 


Stop on error 




stopp 


Stop process 




sttimer 


Store timer 




sub 


Subtract 




sum 


Sum 




tali 


Timer alt start 




taltwt 


Timer alt wait 




testerr 


Test en^or false and clear 




testhalterr 


Test halt-on-error 




testpranal 


Test processor analyzing 




tin 


Timer input 




went 


Word count 
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wsub Word subscript (Areg = Areg + 4*Breg) 

xdble Extend to double 

xor Bit-wise exclusive or 

xword Extend to word 

C.4 Additional instructions for T400, T414, T425 and TB 

The indirect instructions in this section may only be executed on a T400, T414 or 
T425 processor. 

cfferr Check single-length floating-point infinity or not-a-number 

Idinf Load single-length infinity 

postnormsn Post-normalize correction of single-length floating-point number 

roundsn Round single-length floating-point number 

unpacksn Unpack single-length floating-point number 

C.5 Additional instructions for IMS T800, T801 and T805 

The instructions in this section may only be executed on T800. T801 and T805 
processors. 

C.5.1 Floating-point Instructions 

The indirect instructions in this section provide access to the T8 series built-in float- 
ing-point processor. Note that the instructions beginning with 'fpu . . .' are doubly 
indirect: they are accessed by loading an entry code constant with a Idc instruction, 
then executing an fperi/o^ instruction, which is itself indirect. As with ordinary indi- 
rect instructions, this indirection is handled transparently by the assembler, 
although the fpentry instmction is also available. 

The floating-point load and store instaictions use the integer Ar&g as a pointer to 
the operand location. 



fpadd 


Floating-point add 


fpb32tor64 


Convert 32-bit unsigned integer to 64-bit real 


fpchkerr 


Check floating en-or 


fpdiv 


Floating-point divide 


fpdup 


Floating duplicate 


fpentry 


Floating-point unit entry: used to synthesize the 'fpu . 
tions. 


fpeq 


Floating-point equality 


fpgt 


Floating-point greater than 
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C.5 Additional instructions for llVfS T800, T801 and T805 



fpi32tor32 


Convert 32-bit integer to 32-bit real 


fpi32tor64 


Convert 32-bit integer to 64-bit real 


fpint 


Round to floating integer 


fpldnladddb 


Floating load non-local and add double 


fpldnladdsn 


Floating load non-local and add single 


fpldnldb 


Floating load non-local double 


fptdnldbi 


Floating load non-local indexed double 


fpldnlmuldb 


Floating load non-local and multiply double 


fpldnfmulsn 


Floating load non-local and muftipfy single 


fpldnisn 


Floating load non-local single 


fpfdnlsni 


Floating load non-local indexed single 


fpfdzerodb 


Floating load zero double 


fpldzerosn 


Load zero single 


fpmuf 


Floating-point multiply 


fpnan 


Floating-point not-a-number 


fpnotfinite 


Floating-point finite 


fpordered 


Floating-point orderability 


fpremffrst 


Floating-point remainder first step 


fpremstep 


Floating-point remainder iteration step 


fprev 


Floating reverse 


fprtoi32 


Convert floating to 32-bit integer 


fpstnldb 


Floating store non-local double 


tpstnil32 


Store non-local int32 


fpstnlsn 


Floating store non-local single 


fpsub 


Floating-point subtract 


fptesterr 


Test floating en-or false and clear 


fpuabs 


Floating-point absolute 


fpuchki32 


Check in range of 32-bit integer 


fpuchki64 


Check in range of 64-bit integer 


fpuclrerr 


Clear floating en-or 


fpudivby2 


Divide by 2.0 


fpuexpdec32 


Divide by 2^^ 


fpuexpinc32 


Multiply by 2^2 


fpumulby2 


Multiply by 2.0 


fpunoround 


Convert 64-bit real to 32-bit real without rounding 


fpur32tor64 


Convert single to double 
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fpur64tor32 Convert double to single 

fpurm Set rounding mode to round minus 

fpurn Set rounding mode to round nearest 

fpurp Set rounding mode to round positive 

fpurz Set rounding mode to round zero 

fpusetetr Set floating error 

fpusqrtfirst Floating-point square root first step 

fpusqrtlast Floating-point square root end 

fpusqtistep Floating-point square root step 

C.6 AdditionalinstructionsforllVIST225J400J425,T800J801, 
T805 

The indirect instructions in this section supplement the T414's integer instruction 

set. 

bitcnt Count the number of bits set in a word 

btirevnbits Reverse bottom n bits in a word 

blirevword Reverse bits in a word 

crcbyte Calculate ORG on byte 

crcword Calculate Cyclic Redundancy Check (CRC) on word 

dup Duplicate top of stack 

pop Pop processor stack 

Iddevid Load device identity 

wsubdb Form double-word subscript 

The following 2-dimensional block move instructions apply to the IMS T400, T425, 
T800,T801 and T805 only: 

moveZdall 2-dimensional block copy 

move2d{nit Initialize data for 2-dimensional block move 

move2dnonzero 2-dimensional block copy non-zero bytes 

move2dzero 2*dimensional block copy zero bytes 

0.7 Additional instructions for the IIVIS 1225, 1400, T425, T801 
and T805 

The indirect instructions listed in this section provide debugging and general 
support functions. 

dfjObreak Clear jump break enable flag 

setjObreak Set jump break enable flag 
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testjObreak Test if jump break flag is set 

timerdisableh Disable high priority timer intenaipt 

timerdisablel Disable low priority timer interrupt 

iimerenableh Enable high priority timer intemjpt 

timerenablel Enable low priority timer interrupt 

Idmem^artval Load value of MemStart address 



C.8 Instructions supported by 'sequential code insertion' 

The instructions in this section can be used when 'sequential code insertion' is 
enabled by the 'G' compiler option. Note: Only use those instructions which exist 
on the target processor may be used. For example, floating point instructions 
{those beginning with fp) may not be used on T4 series transputers. 



adc 


add 


and 


bent 


bitcnt 


bitrevnb'its 


bitrevword 


bsub 


ccnti 


cflerr 


cj 


crcbyte 


crcword 


csngi 


csubO 


cword 


diff 


div 


dup 


eqc 


fmul 


fpadd 


fpb32tor64 


fpchkerr 


fpdiv 


fpdup 


fpeq 


fpgt 


fpi32tor32 


fpi32tor64 


fpint 


fpldnladddb 


fpldnladdsn 


fpldnldb 


fpfdnldbi 


fpldnfmuldb 


fpldnlmuisn 


fptdnlsn 


fpldnlsni 


fpldzerodb 


fpldzerosn 


fpmul 


fpnan 


fpnotfmite 


fpordered 


fpremfirst 


fpremstep 


fprev 


fprtom 


fpstnldb 


fpstn!i32 


fpstnlsn 


fpsub 


fptesterr 


fpuabs 


fpuchki32 


fpuchki64 


fpuclrerr 


fpudivby2 


fpuexpdoc32 


fpuexpinc32 


fpumulby2 


fpunoround 


fpur32tor64 


fpur64tor32 


fpurm 


fpurn 


fpurp 


fpurz 


fpuseterr 


fpusqrtfirst 


fpusqrifast 


fpusqrtstep 


gf 


J 


ladd 


lb 


Idc 


Iddevid 


Idiff 


Idinf 


tdiv 


Idl 


ld!p 


Idmemstartvaf 


Idnl 


fdnip 


Idpi 


Idpti 


Idfimer 


Imul 


IshI 


fshr 


isub 


Isum 


mint 


move 


move2dall 


move2dinit 


move2dnon- 


zero 


move2dzero 


mul 


norm 


not 


or 


pop 


postnormsn 


prod 


rem 


rev 


roundsn 


sb 


seterr 


shI 


shr 


sti 


stnl 


sttimer 


sub 


sum 


festerr 


testhalterr 


testpranat 


unpacksn 


went 


wsub 


wsubdb 


xdble 


xor 


xword 











ASM pseudo-operations are also pemiitted when sequential code insertion is 
enabled. 
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This appendix describes the facilities for inserting transputer rnstmctlons into 
Occam programs, using the asm construct. 

D.1 Inline transputer code insertion 

The Occam compiler supports the insertion of transputer code directly into an 
Occam program. The facility must be specificafly enabled on the command line. 
Two levels of insertion are available. 

D.1.1 Sequential code insertion 

'Sequential code insertion' allows access to all transputer instructions on the 
processor except those which affect parallel processes and scheduling. A list of 
instructions supported by this facility can be found in section C.8. 

D.1.2 Full code insertion 

Tull code insertion' allows access to all transputer instmctions supported by the 
processor where the process is running. A list of instnjctions can be found in 
Appendix C. 

D.2 ASM construct 

The ASM construct provides the ability to insert transputer code sequences Into 
Occam programs. 

D.2.1 Syntax 

process = asm.construct 

asm.construct = asm 

{ asmJine } 

asmJine = primary.op constantexpression 

I foad.or.store.op name 

I branch.op i label 

I branch.op name 

I secondary.op 
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D.2 ASM construct 



labefdef = 
primary.op = 
load.or.store.op 

branch.op = 
secondary.op 
pseudoMp = 



asm.exp 



pseudo.op 
tabeldef 

•Jabei 

any primary instmction (in upper-case letters) 

LDL I LDNL | LDLP | LDNLP 
STL I STHL 

J I CJ I CALL 

any secondary instruction (in upper-case letters) 

LD asm.exp 

LDAB asm.exp, asm.exp 

LDABC asm.exp, asm.exp, asm.exp 

ST element 

STAB element, element 

STABC element, element, element 

BYTE {, constant.expression } 

WORD {, constant expression ) 

ALIGN 

LDLABELDIFF -.label- : label 

RESERVELOWWS constantexpression 

ADDRESSOF element 
ADDRESSOF foutine.name 
expression 



Note: Inslnjctions should be specified in uppercase. 

ASM instructions 

The primary instructions which perform loads and stores are allowed to take a 
symbolic name as their operand; they evaluate to the primary instruction with an 
operand equal to that symbol's offset in workspace. Note that this means, for 
example, that ldl x where x is a non-VAL parameter, will return the pointer to x. 
This also means that if x is a non-(ocal variable, the operand used will be the vari- 
able's offset in the non-local workspace. Primary instructions with symbolic name 
operands should only be used in special cases; you would normally use the 
pseudo ops as described below. 

The assembler will optimize away primary instructions which are known to be no- 
ops. These are: 



AJW 



ADC 



LDNLP 
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PFIX Should be used where a nop byte Is required, or the BYTE pseudo-op 
could be used. 

Secondary instructions, and the fpentry instructions, simply expand out to the 
correct byte sequence, as expected. 

Branching to a label defined within the same procedure or function is permitted. 
(Two labels with the same name may not appear in the same procedure.) 

Branching to a PROC or FUNCTION which is in scope is pemnitted, but it is the 
responsibility of the programmer to load the parameters for the call con-ectly. 

Pseudo operations 

The pseudo.op operations are defined as follows; 



LD 


Loads a value into the Areg. May use other stack slots and/or 
temporaries. 


LDAB 


Loads values into the Areg and Breg. The left hand expres- 
sion ends up in Areg. May use other stack slots and/or tempo- 
raries. 


LDABC 


Loads values into the Areg, Breg and Creg. The leftmost 
expression ends up in Areg. May use temporaries. 


ST 


Stores the value from the Areg. May use other stack slots 
and/or temporaries. 


STAB 


Stores values from the Areg and Breg. The left hand element 
receives Areg. May use other stack slots and/or temporaries. 


STfiBC 


Stores values into the Areg, Breg and Creg. The leftmost 
element receives Areg. May use temporaries. 


BYTE 


Inserts the following constant BYTE value(s) into the code. 
The expression may be either a single BYTE, or a byte table 
or string, or a comma separated list of such items. 


WORD 


Inserts the following constant INT value(s) into the code. The 
expression may be eithera single integer, or an integer table, 
or a comma separated list of such items. 


LDLABELDIFF 


Calculates the di^erence, n, between hvo labels and inserts 
aLDCn. 


RESERVELOWWS 


Reserves 'below wokspace' slots. This ensures that the 
specified number of words are reserved below the current 
process's workspace, and will not be allocated to any other 
concun-ent process. The specified expression must be a 
compile-time integer constant. 


ALIGN 


Inserts zero or more PFIX Instructions until aligned to a 
word boundary. Currently not implemented. 



Note: that arbitrarily complicated expressions are permitted, including function 
calls. For example: 
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ASM 

LDABC a[x], y+27, f{p,q,r) 
STABC a[f{w,x,y)], z, a[9] 

Expressions used in load pseudo-ops must be word sized or smaller. To load a 
floating point value, use a LD ADDRESSOF name to load its address, then a 
FPLDNLSN or FPLDNLDB as required. Eiements used in store pseudo-ops must 
be word sized or smaller. 

ADDRESSOF operator 

The ADDRESSOF operator fs used in the LD, ldab, and ldabc pseudo-ops, and 
can be applied to any variable, constant expression, or routine name. It returns a 
word containing the machine address of that object. 

Special names 

The following special names are available as constants inside asm expressions. 

. wssiZE Evaluates to the size of the cun-ent procedure's workspace. This 

will be the workspace offset of the return address, except within 
a replicated PAR, where it will be the size of that replication's 
workspace requirement. 

. VSPTR Evaluates to the workspace offset of the vectorspace pointer. If 

inside a replicated par, it points to the vectorspace pointer for 
that branch only. A compile time error is generated if there is no 
vectorspace pointer because no vectors have been created. 

. STATIC Evaluates to the workspace offset of the static link. If inside a 

replicated par, it fMints to the static link for that branch only. A 
compile time error Is generated if there is no static link. 

For example, to determine the return address of a procedure, you would use: ldl 
.WSSIZE There is no checking of suitability', hence, for example, J .WSSIZE is 
legal. 

Channels 

Channels may be accessed in asm; they are considered to be a pointer to a 
channel word. Thus 'loading' a channel will load a pointer to the channel word, and 
loading the 'address' of a channel will load a pointer to a pointer to the channel 
word. 
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Alias 



If two or more expressions denote the same memory address, then the 
expressions are aliases or one another. 



Alias check 



A program compilation check that ensures that names are unique within a 
given scope. 



Analyse 



A transputer input pin which forces the processor to halt at the next 
de-scheduling point, toallowthestateofthe processorto be read. To assert 
the Analyse input on a transputer In the context of 'analyzing a network', 
to analyze all transputers in that transputer network. 



Backtrace 

Within the debugger an simulator tools, to move from a position within a 
procedure or function body to the call of that procedure or function. 

Big endian 

The opposite of little endian — see below. 

Bootable code 

Self-starting program code that can be loaded onto a transputer or trans- 
puter network down a user link and run. Bootable code is produced by 
icollectfrom linked units (single transputer programs) or configuration 
binary files (for configured programs). 

Bootstrap 

A transputer program, loaded from ROM or over a link after the transputer 
has been reset or analyzed, which initializes the processor and loads a 
program for execution (which may be another loader). 
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Capability 

A text string which identifies a transputer resource (or resources). 

Compiler library 

A group of Occam library routines that are used by the compiler to imple- 
ment extended arithmetic and transputer system operations. 

Configuration 

The association of components of a program with a set of physical 
resources. Used in this manual to refer to the specific case of allocating 
software processes to processors m a network, and channels to links 
between processors. The term is also used, depending on the context, to 
describe the act of deciding on these allocations for a program, the configu- 
ration code which describes such a set of allocations, and the act of 
applying the configurer to a configuration description. 

Con^gurer 

The tool which assigns processes and channels on a specified configura- 
tion of transputers. The output from the tool is a configuration binary file for 
input to icollect. 

Connection manager 

The functionality provided by the LInkops part of the host file server. 
Provides and maintains connections to transputer systems across a 
network and is used by the session manag er to select a transputer system 
and maintain unique access to that system. 

Core dump 

A memory dump. Core dumps are required as part of the process of debug- 
ging multitransputer programs that incorporate the root transputer 

Communicating Sequential Processes (CSP) 

A theory and notation, developed by Professor Tony Hoare, for describing 
systems made up of concurrent processes which communicate via chan- 
nels. The Occam model of concun*ency is based on CSP. 



Deadlock 



A state m which one or more concun^ent processes can no longer proceed 
because of a communication interdependency. 
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Error modes 

The compilation mode of a program that determines wrtiat happens when 
a program error (such as an array bounds violation) occurs. Pnagrams are 
compiled by ice in UNIVERSAL mode, which is the mode that can be 
mixed with HALT and STOP code generated by other INMOS compilers. 

Error signal (or error flag) 

In the transputer, an external signal used to indicate that an error has 
occurred in a running program. Also refers to one of the system control 
functions on transputer networks. En'or signals can be OR-ed together on 
transputer boands to indicate that an error has occun-©d in one of the trans- 
puters in a network. 

Ethernet 

A LAN technology based on a passive coaxial cable which transmits at 10 
Mbps. 

Extended data types 

The Occam data types iNTie, iht32, int64, real32 and REAL64. 

External memory interface (EMI) 

The signals which connect a transputer to external memory, consisting of 
address and data buses and a number of control signals. Most of the 32 
bit transputers (T4xx and T8xx) have a programmable EMI which can be 
configured for different types and speeds of extemal memory device. 



Event 



An input signal to the transputer which can be used an external intermpt. 
The event input can be treated by a pnxess as a (zero length) communica- 
tion. 



Free variables 



Variables which are refen-ed to in a function or procedure, but declared 
outside of it. 



Gateway 



A dedicated computer that connects two or more networks, and routes 
messages between them. 
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Hard channels 

Channels which are mapped onto Itnks between pnxessors in a trans- 
puter network (see also soft channels). 



Host 



The cx)mputer to which a transputer system is connected and which poss- 
ibly also provides file system access and terminal I/O. 



Host file server 



A server which provides access to the filing system and terminal I/O of a 
host operating system. 



Include file 



A file containing source code which is incorporated Into a program using 
the C #include (#INCLUDE for occam) directive. Include files are, by 
convention, given the .h extension in C; Occam include files are given the 
extension .inc. 



LAN (Local Area Network) 

Any computer network that works over short distances at high speeds. 

Library 

Acoliection of separately compiled procedures orfunctions, created by the 
toolset librarian ilibr, which may be shared between parts of a program 
or between different programs. 

Library build file 

A file containing a list of input files for the librarian tool ilibr. Each file 
forms a separately loadable module in the library. Library build files should 
have the .Ibb extension. 

Library usage file 

A file listing the libraries and separately compiled units used by another 
library. Library usage files must have the . liu extension. 



Link 



In the context of transputer hardware, the serial communication link 
between processors. 
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In the context of program compilation, collecting together all the compiled 
code for a program, resolving all references and placing the collected code 
into a single file. 

Linker 

The program or tool which links a program or compilation unit 

Linkops 

The recommended INMOS link interface, used by iserver 1.5. 

Little endian 

The transputer is totally 'little endian', i.e. less significant data is always 
held in lower addresses. This applies to bits in bytes, bytes in words and 
words in memory. 



Loader 



Depending on the context, refers to the part of the host file server which 
loads a transputer network or to a small program which is loaded into a 
transputer, and which then distributes code to other transputers and loads 
a larger program on top of [tself. 



Makefile 



An input file for a 'make' program. A makefile contains details of file depen- 
dencies and directions for rebuilding the object code. Makefiles are created 
for the toolset using imakef . 



Network 



Depending on context may refer to a conventional computer network or a 
set of interconnected transputers. 



Object code 



Intermediate code between source and bootable code. Object code 
cannot be directly loaded onto a transputer and run. The compiler and 
linker tools generate object code. 
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Peek and poke 

To read (peek) and write (poke) focafions in a transputer's memory via a 
link, while the transputer is waiting to be booted, 

PostScript 

PostScript is a device-independent, interpreted language for describing 
the layout of text and graphics on a page. It is used by a large number of 
printers and software applications as the standard means of transferring 
graphics data. 



Preamble 



The part of a transputer loader program that initializes the state of the 
processor. 

Priority 

In the transputer, the priority level at which the cun^ently executing process 
is being run. INMOS transputers support two levels of priority, known as 
'high' and 'low'. 

Process 

Self-contained, independently executable code. 

Protocol 

The pattern (type, etc.) of communications between two processes, often 
including communications on more than one channel. Protocols can be 
defined in Occam and must be spedfied when a channel is declared. 



Reset 

The transputer system initialization control signal. 

Root transputer (or root processor) 

The processor in a transputer network which is physicaify connected to the 
host computer, and through which the transputer network is loaded. 



Separate compilation 

A self-contained part of a program may be separately compiled, so that 
only those parts of a program which have changed since the last compila- 
tion need to be re-compiled (see also makefile). 
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Server 

A program running on a host computerwhich provides access to the filing 
system and terminal I/O of the host for the transputers, or access to the 
transputer system from the host. The server can also be used to load the 
program onto the nehvork. 

Session manager 

That pari of the server which maintains unique access {a session) to a 
transputer system when requested by a user. 

Soft channels 

Channels declared and used wthin a process running on a single trans- 
puter (see also hard channels). Soft channels are implemented by a 
single word in memory. 



Standard error 



The host system error handler. Erors directed to standard error are 
displayed in a host-defined way, for example, on the terminal screen. For 
details of how to mod 1^ standard en-or on the system, consult the operating 
system documentation. 



Standard input 



The host system input handler. Specifies the standard input device^ for 
example the terminal keyboard or a disk file. For details of how to modify 
standard input on the system, consult the operating system documenta- 
tion. 



Standard output 



The host system output handler. Specifies the standard output device, for 
example, the terminal screen ora disk file. For details of howto modify stan- 
dard input on the system, consult the operating system documentation. 



Subsystem 



In transputer board architecture, the combination of the Reset, Analyse 
and Error signals which allows one board to control another board 
connected to its subsystem port. 



Target transputer 



The transputer on which the code Is Intended to run. The transputer type, 
or a restricted set of types defined In a transputer class, is defined when 
the program is compiled, using command line options. 
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Transputer Module (TRAM) 

A range of small printed circuit boards which t/pically hold a transputer, 
some memory and, optionally, some other application specific hardware. 
TRAMs can be interconnected via links to buifd systems based on a 
number of motherboard architectures. For more information see the 
iq systems databook. 



Usage check 

A compilation check that ensures no variables are shared between parallel 
processes, and that enforces rules about the use of channels as unidirec- 
tional, point-to-point connections. 

User link 

■The connection of a transputer resource to a host computer. 



Vector space 

The data space required for the storage of arrays within occam code (see 
also workspace). 



Worm 



A program that distributes itself through a network of transputers (perhaps 
with an unknown topology) and allows all the processors in the network to 
be loaded, tested or analyzed. 



Workspace 



The data space required by an occann process. When used in contrast to 
vector space, refers to the data space required for scalars within the 
occam code. 
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.STATIC, 248, 292 

.VSPTR. 248, 292 

.WSSIZE, 248, 292 
#CCMMENT, 8 
#IMPORT, 8 

#INCLUDE, 8, 51,52, 53 
in configuration language, 263 

#OPTION, 8 

#PRAG»4A, 8 
EXTERNAL, 200 
LINKAGE, 43 
TRANSLATE, 201 

#pragma 
IMS_nolink, 211 
IMS_translate, 201 

#SECTION,43 

#USE, 8, 52, 55 
in configuration language, 263 



Abbreviation, configuration 
languagBj 79^ 266 

Abort, 120 
interrupt, 45 

link communication, 258 
program, 45 

ADDRESSOF, 292 

Alias, 293 

Alias check, 48, 293 

Alias checking, warning messages, 
49 

Alignment, word, 240 



Allocating 
channels to links, 242 
specHic workspace locations, 241 

Analyse, 105, 135,241,293 
use when debugging, 107 

ANSI C toolset, 68 

ARC, 69, 78, 85, 264 

Areg, 134,281,291 

An^y 
as argument, 157 
Occam, 276 
of channels, 242 
passing between languages, 203 

ASM, 245, 246 
channel use, 292 
examples, 247 
predefined names, 248 
syntax, 289 

Assembly code 
direct instructions, 246 
indirect Instructions, 246 
insertion into Occam, 245 
instmctlon set, 281 
operands, 246 
prefix instructions, 246 
primary operations, 246 

ASSERT, 48 

Assigning code to transputers, 14 

Automated program building, 97 

B 

6004,44,106 

B008, 107 
PC motherboard, 105 

B014,VME motherboard, 105 

B016,VME motherboard, 105 

Backtrace, 157, 174, 177,293 
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Backus-Naur Form, configuration 
language, 263 

Big endian, 293 

Binary output, ieprom, 235 

BNR See Backus-Naur Form 

Boards 
boot from link, 105 
boot from ROM, 105 
connections, 105 
IMSB004J06 
IMSB008J05 
IMS B014, 105 
IMS B016, 105 
types, 106 

BOOL, 276 

Boot from link 
boards, 105 
loading mechanism, 104 

Boot fn^m ROM 
boards, 105 
code, debugging, 120 

Bootable code, 44, 293 
creating, 33 

Bootstrap, 293 

BptrO, 134 

Bptr1,134 



I BREAK I key, 45 

Breakpoint, 146 
clearing, 175 
hardware support, 1 25 
phantom, 155 
setting and clearing, 128 

Breakpoint debugging. See Debug- 
ging; Interactive debugging 

Brag, 134,282, 291 

Buffering processes, 113 

Build files, library, 296 

BYTE, 276 



C. ENTRY, 30 

C,ENTRYD,29 

C.ENTRYD.RC, 29 

callc.lib,213, 214 

callc.lnk, 212 

Capability, 294 

CASE, debugging occann, 148 

CAUSESRROR, 260 

CHAN, 276 

CHAN OF SP, 41, 111 

Change control, 54 

Channel, 4 
See a/so CHAN OF 
array, 242 

array constmdors, 239, 243 
checking, 49 
configuration, 68 
direct, 85 
edge, 85 

fault handling, 101,257 
hard, 296 
initialize, 102 
optimize, 187 
place at address, 240 
piacement, 85, 91,242 
reinitialize, 102,258 
reliable, 101 
reserved, 224 
reset, 102,259 
retyping, 243 
soft, 85, 299 
usage, 49 
usage checking, 49 
use within ASM, 292 
virtual, 85, 86 

channel . h, 276 

Check 
alias, 48 
channel, 48 
configuration, 102 
usage, 48 
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Checking, occam code, 246 

Clearing 
breakpoint, 175 
en-or flag, 108, 126 

clibs, Ink, 31,232 

clibsrd. Ink, 31, 213, 232 

Clock, 134 
displayed on Monitor page, 136 

ClockO, 134 

Clockl, 134 

cnonconf . Ink, 29 

Code 
allocation in memory, using 

PLACE statement, 239 
insertion, 239, 245 
placement, 90, 181 
position in memory, 88, 181 

Collecting, simple program, 37 

Collector, 18 

Communicating Sequential 
Processes, 4,294, 305 

Communication. See Channel 

Compilation, 42 
information, 43 
separate, 52 
unit, 52 

Compiler 
directive, 43 
libraries 

introduction, 9 

Occam, 212, 219, 294 
optimizations, in debugging, 158 

Compiling, 17 
for debugging, 117 
for other transputer types, 39 
introduction, 42 
simple example, 35 

Concurrency, hardware support, 2 

CONFIG, 69, 264, 267 



Configuration, 67, 294 
channels, 85 
checking, 102 
code & data placement, 10 
debugging considerations, 100, 

101,156 
description, 67, 70 

multiple transputer example, 94 
examples, 72, 73, 80 

multiple transputer, 93 

simple, 36 

virtual routing, 194 
hardware description, 68, 74 
host connection, 79 
language, 69 

abbreviations, 79 

constraints, 269 

introduction, 10 

predefinttions, 265 

syntax, 263 
libraries of linked units, 82 
mapping, 68 

channels, 87 

description, 83 

processes, 84 
mixed language, 67 
model, 68 

Occam scope mles, 68 
reliable channels, 101, 257 
single transputer program, 38 
software description, 68, 81 
summary, 100 
using imakef ^ 97 
virtual routing, 86 

Configurer, 18,294 
producing debuggable programs, 
118 

CONNECT, 69, 264 

Connecting 
boards, 105 
links, 69, 264 
subnetworks, 105 

Connection manager, 294 

Constants 
include files, 110 
sharing, 52 
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Core dump, 294 
Creg, 134,283,291 
CSP,4,294,305 
cstartrd.lnk, 29, 212 
cs tar tup. Ink, 29, 212 

D 

deadfix.occ, 150 
Deadlock, 148, 294 
deadlock, occ, 149 
Debug library, 142 

DEBUG. TIMER, 150 

Debuggable programs, 116 

Debugger, 19 
hints, 147 
kernel, 123 
quitting, 175 

Debugging, 115 

See also Interactive debugging; 
Monitor page; Post-mortem 
debugging 

abusing hard links, 151 

arrays as arguments, 157 

boot from ROM code, 120 

breakpoint, 172 

catching concun^ent processes, 
155 

commands, only available in inter- 
active mode, 128 

compiler optimizations, 158 

confidence check, 153 

configured programs, 118, 156 

deadfix.occ, 150 

deadlock . occ, 149 

direct channel functions, 118 

error modes, 118 

errors, 158 

examining the active network, 152 

example, C, 159 

goto process, 178 

hard parity errors, 120, 122 

impoilant points, 151 



information, 117 

I INSPECT I, 152 



inspecting channels, 177 
inspecting variables, 176 
interactive, 116, 123, 172 

disabling, 118 
I INTERRUPT] key, 153 
invalid pointers, 147 
large shift values, 157 
library, 142 
library funclions^ in absence of 

idebug, 145 
loading pn>grams, 106 
low level, 132 
memory size, 156 
mixed language, 116 
Monitor page, 132 
post-mortem, 115, 120,175 
program crashes, 1 54 
program hangs, 154 
root transputer, 123 
seterr, 156 

soft configuration channels, 147 
tracing processes, 177 
undetected program crashes, 154 
useof isim, 116 
virtual links, 152 

Default 
command line arguments, 27 
error mode, 42, 118 
memory map, 181 
transputer type, 42 

Direct channels, 85, 101 

Direct instructions, 246, 281 

Disable 
alias checking, 49 
interactive debugging, 48, 118 
range checking, 47 
run-time checks, 46 
usage checking, 49 
vector space, 50 
virtual routing, 48, 117 

Display 
debugger help page, 129 
memory, 137 
memory map, 136 
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Monitor page, 133 
object code, 44 
process queues, 178 
source code, 130 

DO, 69, 268 

DOS, 111 

Down, subsystem wiring, 105 

Dynamic code loading, 239, 250 
examples, 253 



EDGE, 69, 77, 264 

Edge 
channel, 85, 86 
declaring, 77 

EMI. See External Memory Inter- 
face 

Entry points 
C, ENTRY, 30 
C.ENTRYD, 29 
C.ENTRYD.RC, 29 

Environment variables, 26, 34 

EPROM programming, 21, 233 
collecting, 236 
configuring, 236 
tools, introduction, 21 

Error, 105,241,295 

En-or 
detection, disable, 46 
modes, 45, 295 

default, 42 

HALT, 45, 295 

in debugging, 118 

STOP, 45, 295 

UNDEFINED, 46 

UNIVERSAL, 46, 295 
reporting, 25 

Error flag 
clearing in a network, 108, 126 
displayed on Monitor page, 134, 

135 
of a subsystem, 105 



setting, 239, 260 
Ethernet, 295 
Event, 141 
Event, 295 

Examples 

ASM, 247 

collecting, 37 

configuration, 36 

configuration mapping, 92 

deadlock, 149 

debugging C, 159 

debugging in post-mortem mode, 

175 
debugging Occam, 168 
dynamic code loading, 253 
facs.c, 160 
facs.occ, 169 
linking equivalent occam 

process, 232 
multiple transputer, 93 
multiplexing to host, 113 
network description, 80 
optimized filter program, 194 
passing C parameters, 273 
phantom breakpoints, 155 
pipeline sorter, 57 
placing channels, 242 
resetting B004, 241 
retyping channels, 244 
running a program, 37 
simple program, 34 
single. occ, 34 
single transputer program, 38 
skip load, 107 
software description, 83 
sorter. occ, 62 
type 1 interface, 227 
type 2 interface, 229 
type 3 interface, 231 
use of debugging library, 144 
virtual routing, 196 

Executable code, 17 

Extended data types, Occam, 295 

Extensions, tile, 22 

External memory interface, 295 
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Extraordinary use of links, 239, 256 



facs.c, 160 
compiling and loading, 164 

f acs , occ, 1 69 
compiling and loading, 171 

File 
extensions, 22 
imakef , 23 
streams, 110 

Floating point 
instmctions, 285 
registers, 249 

FORTRAN, xviij 20 

FPError, 134 

FptrO, 134 
Fptrl, 134 
Free memory, 42 
Free variables, 295 



Gateway. 295 
Getting started, 33 
Global static base, 209, 213 
Grid, network topology, 3 

H 

HALT en-or mode, 45 
in debugging, 118 

HaltOnError, 45, 134 

Hard channels, 296 

Hardware configuration description, 
74,264 

Hardware support 
forbreakpointing, 125 
for concurrency, 2 



Heap area, mixed language 
programs, 213, 225 

Help, page in debugger, 129 

Hexadecimal format 
for environment variables, 27 
for EPROM, 235 
syntax, 27 

HOST, 79» 265 

Host, 296 
access to services, 109 
channel protocols, 111 
communications, 109 
connection, in configuration 

language, 79 
dependendes, 25 

command line syntax, 25 

filenames, 26 

search paths, 26 
environment variables, 26 
versions, xv 

Host file server, 296 
file streams, 110 
introduction, 109 

Hostio library, 110 

hostio.inc, 110 

hostio. lib, 110 

I 

IBM PC, 7, 111 
386, 25 

IBOARDSIZE, 27, 34,42 

ice, 9 

ICCARG, 28 

icconf, 118 

ICCONFARG, 28 

icollect, 18 

ICOLLECTARG, 28 

ICOKDB, 27, 34 

idebug, 19 
help page, 129 
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IDEBUGSIZE, 27 
idump, 20 
iemit, 21 

ieprom, 21,233, 235 
IF, 69, 98, 266 

debugging occam, 148 
ilibr, 20 
ILIBRARG, 28 
ilink, 17 
ILINKARG. 28 
ilist,20 
ILISTARG, 28 
imakef , 20, 39, 54, 97 
imap, 20 

Importing C functions, 213 
IMST800, 135 

Include fife, 110.296 
occonf .inc, 70, 187, 192 

Indirect instmctions, 246, 282 

init.heap, 214 

init. static, 214 

Initialize 

channel, 102 

link, 258 

parity checked memory, 126 

InputOrFail.c, 102 

InputOrFail.t, 101 

INQUEST, xvii 

I INSPECT 1 , 176 

Instruction pointer, 134 
invalid, 147 

Instruction set, 281 

INT, 276 

INT16, 276 

INT32, 276 

INT 64, 276 

Intel extended hex format, 235 



Intel hex format, 235 

Interactive debugging, 116, 123, 
129 

See also Debugging 
addresses of variables, 166 
backtracing, 166, 174 
backtracing to main{) , 167 
breakpoint commands, 132 
browsing source code, 130 
clearing a breakpoint, 175 
compiler option, 48 
disabling, 48, 118 
entering #include files, 168 
inspecting by expression, 167 
inspecting variables, 131, 166, 

173 
jumping down a channel, 167, 

174 
jumping down channels, 131 
locating to code, 130 
modifying a variable, 167. 174 
modifying variables, 132 
program loading, 126 
program temiination, 128 
quitting, 168, 175 
resuming program, 174 
runtime kernel, 123 
setting breakpoints, 165, 173 
starting a program, 166, 173 
tracing procedure calls, 131 

Intemjpt, program, 45 
in debugging, 153 

Invalid pointers, 147 

Iptr, 134,281 

tptrlntSave. 134 

/q systems, 102, 108, 126 

ISEARCH, 27, 34 

i server. 18, 103, 109 

ISESSION, 27 

isim, 21,65, 146 

ISIMRATCH, 27 

iskip, 18. 103 

ispy, 102,108, 126 

ITERM, 27 
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Jump, in ASM code, 248 

Jumping down a channel, 131, 167, 
174 



K 

KERNEL. RDN, 250 



Label, in ASM code, 248 

LAN, 296 

Large programs, 53 

Large shrfl values, 157 

Librarian, 20 

Library, 296 
build files, 296 
building, 55 
C njntlme 
full, 232 
reduced, 232 
compiler, 9 
debugging, 142 
linking supplied librarieSj 28 
maths, 9 
Occam, 9, 221 
of linked units, 82 
usage files, 296 
using. 54 

Link, 3, 296 
addresses, 243 
failure, 256 
introduction, 2 
recovery from failure, 258 
renitialize, 258 
virtual, 86 

link, 74, 265 

linkaddr . inc, 243 

Linker. 17, 297 
indirect files, 28 



startup files, 28 
clibs . Ink, 232 
clibsrd,lnk,232 

Unking 
introduction, 43 

mixed language programs, 212 
simple example, 35 

Linkops, 297 

linkquota, 75, 92, 190, 265 

Lister, 20 

Little endian, 297 

LOAD . BYTE .VECTOR, 250 

LOAD . IKPUT . CHANNEL, 250 

LOAD . INPUT . CHANNEL , VECTOR, 
250 

LOAD . OUTPUT . CHANNEL, 250 

LOAD . OUTPUT . CHANNEL . VECTOR, 
250 

Loader, 297 

Loading programs, 44, 103 
for breakpoint debugging, 106 
for debugging, 106 
for interactive debugging, 126 
introduction, 18 
methods, 104 
onto boards and subnetworks, 

104 
tools, 103 

LoadStart, 181 

location. code, 75, 90, 184, 265 
location. vs, 75, 90, 184, 265 
location. ws, 75, 90, 184, 265 
Logical processor, 69 
Low-level programming, 239 

M 

MAIN. ENTRY, 222 
procedure interface, 226 

MAKE, 66 

Makefile generator, 20, 39, 54 



72TDS366 01 



March 1993 



Index 



315 



Makefiles, 297 

MAP, 69, 268 

MAPPING, 69, 264, 267 

Mapping 
channels, 87 
description, 83 
examples, 92 

in configuration description, 267 
processes, 84 
with MAPPING, 87 
without MAPPING, 88 

Master transputer, of a system, 105 

Maths, libraries, introduction, 9 

Memory 
allocation, 50 
initializing, 126, 225 
map, 181 
on-chip, 1 
ordering code, 88 
pladngcode, 90, 181 
reserved words 
IptrlntSave, 134 
WdesclntSave, 134 
reserving, 89 

Memory dump, 123 
example, 176 

Memory dumper, 20 

Memory map, 181 
displayed on monitor page, 136 

memsize, 74, 265 

MemStart, 89, 135 

Mixed language programming, 199 
example, 273 
heap area, 213 
importing C code, 213 
introduction, 11 
linl^ing, 212 
Occam libraries, 221 
reduced runtime library, 220 
static area, 213 
vector space, 221 
woritspace, 221 



Monitor page, 132 
See also Debugging 
breakpoint commands, 139 
command format, 137 
data displayed, 134 
examining memory, 137 
locating processes, 137 
selecting process, 138 
specifying process, 138 
startup display, 1 33 
switching processor, 1 38 

MOSTNEG INT, 240, 247 

MOSTPOS INT, 247 

Motorola S-record format, 235 

Moving code and data areas, 88 

MS-DOS, 7, 25, 26, 27 

Multiplexing, 10 
examples, 113 
processes. 111 

N 

NETWORK, 69, 264 

Networi<, 297 
configuration, 67 
description, 75 
examples, 80 
grid, 3 
pipeline, 3 
Tree, 3 

nfix, 246 

NODE, 68, 69, 264 
attributes, 74 

nodebug, 75, 265 

NOP, 291 

noprof ile, 75, 265 

NotProcess, 135 



Object code, 297 
displaying, 44 

Object file, format, 7, 17 
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array, 276 

compiler libraries, 9, 294 

configuration language, 263 

equivalent process, 222 

extended data types, 295 

function return values, 272, 277 

interface code, 222 

fibraries,221 

iow-tevei programming, 239 

maths libraries, 9 

mixing with C code, 199 

programming model, 8 

programs, 41 

standard libraries, 9 

Occam 2 toolset, introduction, 7 

occaiii2 . Ink, 30, 43, 212 

occamS.lnlc, 30,43, 212 

occama.lnk:, 30, 43, 212 

occonf, 10, 67, 87, 118 
interaction with idebug, 100 

occonf .inc, 70, 92, 186, 187, 
192 

On-chip memory, 1 
use for program stack, 225 

On-chip RAM, 43, 50 

Operating systems 
command lines, 25 
dependencies, 25 
MS-DOS, 25 
SunOS, 25 
UNIX, 25 
VMS, 25 

opr, 246 

Optimization 
code placement, 181 
virtual routing, 187 

Options 

prefix, 25 
unsupported, 31 

order . code, 75, 88, 185, 265 

order -V3, 75, 88, 185, 265 



order. ws, 88, 185,265 
OutputOrFail.c, 102 
OutputOrFail , t, 101 



FAR, 81 

Parallel processing 
example, 62 
introducton, 4 

Parameter passing, 271 , 275 

Parameters 
GSB,213 
Occam and G equivalents, 271 , 

275 
passing by reference, 201 
passing by value, 201 
TIMER, 203 
to KERNEL. RUN, 251 

Parity checked memory, initializing, 
126 

Parity error registers, displayed on 
Monitor page, 136 

Parity errors, post-mortem debug- 
ging, 120, 122 

ParityAddr, 134 

ParityError, 134 

Peek, 298 

pfix, 246, 291 

Phantom breakpoints, 155 

Physical processor, 69 

Pipeline, network, 3 

Pipeline sorter, example configura- 
tion, 93 

Pipelining processes, 113 

PLACE, 51,239 
channels on links, 242 
examples, 240 

PLACED PAR, 81 

Placement 
at address, 239 
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channels, 85, 240 
code, 88, 90, 181 
variable in workspace, 242 

Pointer to channel, 242 

Poke, 298 

PORT, 276 

Port, 241 
place at address, 239 

Post-mortem debugging, 115, 120 
See also debugging 
communication on channels, 141 
communication on links, 141 
communication on virtual links, 

141 
hard parity errors, 120, 122 
locating procedures and func- 
tions, 142 
outline of method, 139 
stopped process, 142 
stopped process location, 140 
waiting on run queue, 140 
waiting on timer queue, 140 

PostScript, 298 

Preamble, 298 

Prefixing rnstructions, 246, 281 

Primary operations, 246 

Priority, 298 

PROC. ENTRY, 223 

procedure interface, 227 

PROC, ENTRY. RC, 223 
procedure interface, 230 

Procedure parameters, 251 

Process, 4, 298 
descriptor, 134 

invalid, 147 
pointers, in debugging, 135 
queue, 135, 140 
scheduling, 260 

PROCESSOR, 68, 69, 267 

Program building, automated, 66 

Program development, introduction, 
13 



Program hangs, debugging, 154 

Program termination, interactive 
debugging, 128 

Programmable memory interface, 1 

Programs, loading, 103 

Protocol, 298 
in debugging, 123 
include files, 110 
i server, 104 
sharing, 52 
SP, 104, 111 
used by standard libraries, 123 

Pseudo operations, 247, 291 

Q 

Queue 
process, 140, 178 
run, 135, 138, 140 
timer, 135, 138, 140 

R 

RAM, 234 

Real-time programming, 3 

REAL32, 276 

REAL64, 276 

Reduced library, 232 

Registers 
Areg, 134, 281 
BptrO, 134 
Bplr1,134 
Breg, 134, 282 
ClockO, 134 
Clockl, 134 
Greg, 134,283 

displayed on Monitor page, 135 
Error, 134 
FPError, 134 
FptrO, 134 
Fptr1, 134 
HaltOnError, 134 
Iptr, 134,281 
ParityAddr, 134 
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ParityError, 134 
TptrO, 134 
Tptr1,134 
Wdesc, 134 

Wreg, 281 

Reinitialise, 102, 258 

Reinitialize 
channels, 102 
link, 258 

RESCHEDULE, 260 

reserved, 75, 89, 183, 265 

Reserved channels, in occam 
equivalent processes, 224 

Reserving memory, 89, 183 

Reset, 105,241,298 
use when debugging, 107 

Retyping, channels, 239, 243 

ROM bootable code, 233 
processing contigurations, 234 

romsize, 74, 265 

root, 74, 265 

Root transputer, 298 
debugging, 106 
loading over, 107 

routecost, 75, 91, 188, 265 

Run queue, 135, 140 

Running programs, 44 
dynamically loaded, 250 
introduction, 18 
simple example, 37 
using jsim, 38 



Scheduling, 239 
Occam processes, 260 

Scheduling lists. See Process 
queue; Run queue 



Scope rules, 147 
Search path, 26 



Secondary operations, 246 

Selective loading, libraries, 55 

Separate compilation, 52. 298 

Separate vector space, 50, 251 

Sequential programming, 4 

Serial links, 1 

Server, 18,299 

Session manager, 299 

SET, 69, 264 

seterr, 156, 260 

Simulator, 21 
use in debugging, 146 

Single step execution, 147 

SKIP, 268 

Skip load 
example, 107 
jn debugging, 123 

Skip loader, 18 

so, buffer, 113 

so. exit, 111 

30. multiplexor, 112 

so. overlapped. buffer, 114 

so . overlapped, multiplexor, 
112 

Soft channels, 85, 299 

Software, virtual routing, 86 

Software description, 81, 267 
example, 82 

sortconf .pgm, 93 

sortsw.inc, 93 

Source level debugging, 129 

SP, 111 

Stack, 225 
overflow detection, 225 
placing in on-chip RAM, 225 

Standard error, 110, 299 

Standard input, 110,299 

Standard output, 110,299 
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Static area, 213 
pointer^213 
requirement, 213 

STOP, 268 

STOP error mode, 45 
debugging, 118 

stopp, 260 

Streamio library, 110 

streamio,inc, 110 

streamio, lib, 110 

Subsystem, 105,299 
wiring, 105 

Sun 4, 7, 25 

SunOS, 7, 25 

Suspending programs, 45 

Symbolic debugging, 129 
See also Debugging 
compiling for, 117 

Synchronized communication, 4 

System services, 1 05 



Target transputer, 8, 299 

TC0FF,7, 17 

terminate. heap. use, 214 

terminate. static. use, 214 

Timeout, 256 
channel input, 101 
channel output, 101 
on links, 257 

TIMER, 276 
parameters, 203 

Timer. See Clock 

Timer queue, 135, 140 

tolerance, 75, 91, 189, 266 

Toolset 
development cycle, 13 



documentation, xvi 
conventions, xvii 
file extensions, 22 
program development, 13 
summary, 12 

TptrO, 134 

Tplrl, 134 

TRAM, 106,241,300 
TRANSPUTER, 27, 33, 104 

Transputer 
architecture, 2 
clock, 134, 136 
in real-time programming, 3 
instruction set, 281 
introduction, 1 
loading, 103 
master, 105 
module, 300 
networks, 3 
operation codes, 282 
products, 4 
root, 298 
targets, 299 
timer, 134 

Tree, network topology, 3 
type, 74, 265 

u 

UART, 240 

UNDEFINED error mode, 46, 47 

UNIVERSAL error mode, 46 
debugging, 118 

UNIX, 25 

Unsupported options, 31 

Up, subsystem wiring, 105 

Usage check, 48, 300 

Usage files, libraries, 296 

User link, 300 

V 

VAL, 69, 276 
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Variable, place in workspace, 242 2 

VAXA/MS,7,25,26,27. 111 

VECSPACE 51 ^» command tine option, 31 

Vectorspace, 50, 51,300 

disabling, 50 

in mixed language programming, 
221 

position in memory, 181 
Virtual channel, 85 

disable. 87 
Virtual link, 85, 152 

Virtual routing, 86 

contralling, 91 

disable, 48, 87 

introduction, 10 

optimization techniques, 187 

software, 86 
VME bus, motherboard, 105 
VMS, 25, 27 

w 

Wdesc, 134 

WdesclntSave, 134 

Wired down> 105 

Wired subs, 105 

Word alignment, placed objects, 

240 
Word length, independence, 240 
WORKSPACE, 51,241 
Workspace, 300 

in ASM code, 247 

in dynamic loading, 251 

in mixed language programming, 
221 

position in memory, 181 
Worm, 300 
Wreg, 281 
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xlinlclib, 256 
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